Welcome to Macintosh Technical Support! 


Your ID: "SUPT. 


Your KEY: 


Welcome to Macintosh Technical Support. We provide developer support. through 
Apple's electronic mail system on TYMNET. Using this system increases gur 
efficiency, which translates into better support for davedouans. eis 


The attached document is the first draft of the user's guide for the 
electronic mail system. The last page is a list. of the TYMNET phone’ ‘numbers, 
sorted by state. To use the system, you'll need a computer (we suggest an 


Apple), a modem, and a phone. You pay for the telephone call, and Apple pays” 
for the electronic mail system charges, with the understanding - that the system 


is to be used for technical support matters. : x 

» 
The first time you log onto the system, you should change your key (password). 
Change it to something that you'll remember, and something non-obvious.. Phease 
keep it secret. If you have problems, or suspect unauthorized use of ‘the 


service, send me a message, or give me a call. For information on changing _ 


your key, type 


S « 
y 
:READ ** CHANGE. KEY a 


When you have a question or problem, send a message to me at the MAC mail 
station. The mailbox is usually checked 3 or 4 times a day (I check it from 
home on the weekends), and we will try for 24 hour turnaround at worst. 


I'd appreciate comments on the document (this is a draft), and on the system. 
Let me know what kind of equipment you're using to access the system, and how 
it works for you. 


OLD USERS OF THE SYSTEM 
If you've been using the system for a while, you'll notice a couple of 
changes. The account name is now SUPT (it used to be APPLE). You send mail to 
MAC rather than MACTECH. Phone numbers are the same. 


1200 BAUD USERS 
If you're experiencing trouble at 1200 baud, and your software uses XON/XOFF 
protocols, be sure and send CONTROL-X CONTROL-R before EMSAPP in talking to 


the system. This lets their software know you're using XON/XOFF for flow 
control. 


Bob Martin 


Mac Tech Support 


es oan 


ELECT 
MAIL 


5/1/83 


Apple Computer, Inc. 
29525 Mariani Avenue 
Cupertino, CA 95914 


Macintosh Tech Support Electronic Mail System 
Users Guide 


ae 
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Introduction 


This document is a users guide for Apple computer third party developers using 
Apple's electronic mail system (EMS). Apple Computer, Inc. uses TYMNET's 
"ONTYME II" message switching network with Apple ][ and Apple /// computers 
to create an effective and efficient computer based message network. 

The ONTYME II message switching system operates on a store and forward basis. 
It accepts messages for transmission, and then either stores them while 
waiting for users to make contact with the service, or delivers the messages 
to on-line designated hardcopy printers. The network is supported by 
Technical Support. 


Messages (mail) are created off line using either an Apple ][{ or Apple ///, 
and then entered into the electronic mail system. 


This service is provided to third party developers to improve communication 
and productivity between Apple and outside developers. 


Each station or user in the Apple account is identified with a unique call 
directing code (CDC) and password. 


All commands entered into the system are preceded with a colon (:), to 
indicate that they are commands and not text. Commands must begin at the left 
margin (column 9). 


The following definitions and conventions are used in the examples given in 
this guide. Refer to page 11 for the ONTYME II command definitions. 


Convention used Definition 

CDC, CDCl, CDC2, etc A call directing code (a user) 
Underlined text Commands typed by the user 

Regular text Text or messages printed by EMS 
(er) A carriage return typed by the user 
(s) A space that is required 

EMS Apple's electronic mail system 


Questions or suggestions regarding EMS should be forwarded to EMS station 
"MAC", 
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Preparing and Sending Messages 


The :SEND command takes the text in your workspace and sends it to the CDC (or 
CDCs) that you specify. 


Managing the Workspace - :TYPE and :ERASE commands 


Anything that is net recognized as a command goes into your workspace as part 
of the message you want to send. So, if you type ";IN" rather than “:IN", the 
erroneous command goes into your workspace. If you are unsure of what text is 
in your workspace, use the :TYPE command to display it. The :ERASE command 
clears the workspace. 


Standard Message Format 


All messages should be created and edited off line, using a text editor of 
your choice. This saves valuable connect time on the EMS 


When preparing a message, do not exceed a 68=-character line length. By 
keeping your lines under 68 characters, you insure that international 
locations will be able to read each line in its entirety. Although there have 
been recent improvements, most international locations still use the older 
telex type equipment which has a 68=character line Limitation. 


Text editors such as Applewriter and the Pascal editor let you set up a 

"boilerplate" file thae includes a right margin (or line length) selection of 
= characters. Using a boilerplate file is a good way of insuring a consistant 
ormat. < 


All messages should be prepared using the following format: 


Format Example 

Date 3/1/83 

Addressee To: MAC tech support 

Sender Fr: Bob Martin "MAC1923" 

Text This is the new standard message 


format for a message sent through 
the ONTYME or telex networks. 

End of message 

and operators 


initials END/ RIM 
Send command : SEND(s )MAC( cr) 


The :SEND command packages up the text in your workspace and sends it to the 
destination CDC. If you want to send the message to more chan one COC, 
separate the CDCs by at least one space. 
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Mail Management 


General information 


The Apple electronic mail system provides tools that allow you to manage your ~~~ Ne 


mail box effectively and efficiently. 
These tools are: 
I. The "IN" list 
II. The "OUT" list 
III. Receiving commands 
IV. Message retrieval 
VY. Cancelling a message 


VI. Control characters 


I. The IN list 


Each time someone sends a message to you an entry is made into a list for all 


messages waiting to be received by your CDC. This list is called your "IN ~ 
list". When you actually ask to "READ" a message, the entry in the "IN list" 


is removed, and entered into the "IN OLD list". 


To see if any messages are in your mail box waiting for you; you examine the 
"IN list" by issuing this command: 


sIN (cr) 


If no messages are waiting, then EMS will respond with "NONE". Otherwise, 
the following information is transmitted to you: 


SENDER SENT MSG# LENGTH 
aaa ddmumyy hh:om bbbb ccc 
aaa = Sending CDC 
ddamyy = Day, month, year that message was sent 
hh:mm = Time message was sent (your local time) 
bbbb = Message number assigned by the EMS 
cece = Number of characters in the message 
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Mail Management 


I. The IN list \ 


To examine the list of messages you have received and read in the last five 
days, issue the command: 


2 IN(s )OLD( cr) 

The following information is transmitted to you: 
SENDER SENT MSG¢ =. READ 
aaa ddmmyy hh:mum bbbb dddd 


The legend is similar to the in list, except (dddd) indicates the date and 
time the message was read, and omits the message length. : 


Now, 1£ you want a message to be re-transmitted to you, type: 
:READ(s) bbbb( cr) 
Il. The OUT list 


Each time you send a message, it is entered on a list of all messages you've 

sent, called your “OUT list”. When the recipient of a single addressed 

message has read it, the entry is removed from your “OUT list™ and placed in 

your “OUT OLD list™ where you have confirmation of its receipt, plus the date \ 
and time it was read. For messages sent to multiple CDC's an asterisk (*) 

will be added before each location which has received it. When all locations . 
have received the message, the entry will be moved to the "OLD OUT list”. 


To see if there are messages waiting to be delivered, examine the "QUT list™ 
by issuing the command: 


:0UT(cr) 


If all your messages have been received, the EMS responds with "NONE". 
Otherwise, the following information is transmitted: 


NAME SENT MSG# 

aaaa ddmamyy hh:am bbbbd 
aaaa = Receiving CDC 
ddumyy = Day, month and year message was sent 
hh:am = Time message was sent (your local time) 
bobb = Message number assigned by the EMS 


Although EMS keeps lists of your unread outgoing messages for up to 14 days 
after transmission, it's a good habit to check your "OUT list” at least once 4 
day. 
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III. Receiving commands 


Mail Management 


If you are a dial-up user you must check your mail box for incoming mail (as 
you do at home). It's recommended that this be done daily. 


To receive your mail from the ONTYME II system, you must use one of the "READ 


commands" listed below: 


But, before entering read commands, make sure you are ready to record the mail 
you will be reading either in memory, or on disk. 


COMMAND 


:READ( cr) 


:READ(s)ALL(cr) 


:READ(s)message number(cr) 


Purpose 
eae 


Transmits the oldest message on 

your IN list, then removes it from your 
IN list and removes your CDC from the 
senders OUT list. 


Transmits all the messages on your IN 
list, removes them from your IN list 
and removes your CDC from the senders 
OUT list. 


Transmits a specific message re- 

cently received to your CDC. This only. 
works if the message is still on either 
your IN list or OUT list. 
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Mail Management 


Iv. Message retrieval 


— 


Any message still on your IN or OUT lists can be retrieved by 
following command: 


:GET(s)message number(cr) 


issuing the 


This command does not automatically transmit the retrieved text; the following 


command should be used to transmit the retrieved text: 


:TYPE(ecr) 


Vv. Cancelling a message 


You can cancel any message sent via your CDC that has not been 
recipients (if some recipients have already read the message, 
notify you). "Message number", below, is the master message 
ONTYME assigned to the message at transmission. 


sCANCEL(s)message number(cr) 


Vie ONTYME IL Control Characters 


EMS uses these control characters: 


(CTRL) # Deletes the last character typed. 
(CTRL) § Stops the data being received. 
(CTRL) Q Starts the data being received. 


read by ali 
ONTYME will 


number that 


CTRL-H is the left arrow on most keyboards. Typing CTRL=S suspends output, but 
it may take 29 characters or so before the EMS recognizes it. To start things 


going again after CTRL-S, type CTRL=-Q. 
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Accessing the Electronic Mail System 


Accessing EMS is done by placing a telephone call to the local TYMNET office 
(see attachment to determine local number) and then "logging" into the EMS 
computer using the "log in" instructions listed below. 


TYMNET/ONTYME II log in instructions 


Proper connection with TYMNET has been made when the following appears on your 
screen: 


XXXXXXXKAKKXKYPIIIIPIOPP xxxrxxG GIGS xraxx9GGG (garbage) 


Respond by typing: 
A 


This lets TYMNET know what terminal speed you're using. 
The system will respond with: 


“please log in:" 


Respond by typing: 
emsapp(cr) 


The system will respond with: 


S&S 


"SONTYME II date time GMT" 

wrpe2 

Respond with: 

Apple.xxx(cr) (xxx = users CDC) 
The system will respond with: 
"REY?" 


Respond by typing your key (password), (it shouldn't echo) followed by a 
carriage return (cr). The system will respond with: 


"ACCEPTED" (please refer to page 9 if "ACCEPTED" sign does not appear). 


A sample log in sequence is shown below: 
xxcocnxx$9G9PPxxxxxxI99GG( garbage) 
A 
=1326-923- 
please log in :EMSAPP(cr) 
id? SUPT.MAC(cr) 


KEY? non printing password is typed (cr) 
ACCEPTED 


), 
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Leaving EMS 


You normally end your EMS session by issuing the command ";QUIT". If there 
are any messages still waiting in your IN list, the following message will be 


printed: 
"MESSAGES WAITING:" = if your IN in list is not empty 


Pressing RETURN (cr) in response to the above message ends the session. Any 
other response will ignore the quit command, leaving you connected to EMS. 


For example: 
:QUIT( er) 
MESSAGES WAITING: (cr) 


DROPPED BY ONTYME [TI 
Gl MAR 83 11:47:35 


Please log in: (message will appear when you have successfully 
terminated from ONTYME II). 


Note: When using Access /// you must press “OPEN“APPLE Q" to exit, 
after you have left ONTYME II. 


To leave the system immediately, use the command: 


:LOGOUT( cr) 
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Symptom or message 


Ring no answer 


Busy signal when call placed 


"ERROR TYPE USER NAME" 
Terminal prints DDOOUUBBLLEE 
"HOST DOWN" 

“please log in" printed 


during session 


"all ports busy” 
"all circuits busy" 


"no such recipient” 


“invalid command" 


“message not on in list" 


"all messages read" 


"group code file not found" 
“invalid message number” 


“invalid user" 


Error Messages 


Action required 


Call message network supervisor. 
Wait 5 minutes and try again. 
Re-type user name. 


Insure that the Apple/software 
is set for full duplex. 


Wait 15 minutes and try again. 
Communications failure: log in again 
and re-start job from point of last 
accepted message. 

Wait 5 minutes and try again. 

Wait 5 minutes and try again. 


"name" printed station name (CDC) 
is not a valid station. 


Command misspelled. 


Message requested is not on IN list 
or the IN OLD list. 


The IN list is empty. 


Group code was either mistyped or 
non-existent. 


Message number with an error was 
entered. 


Prints when the specified "username" 
is not valid in the system. 


NOTE: Error messages with quotes will appear on screen when you are 


logged onto EMS. 
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Error Messages 


Action reauired 


Symptom oF message 


Prints when an invalid message number 


“message #77" 
is entered in GET or READ commands. 


Prints if user tries to cancel a 


"message not on out list” 
message that has already been read. 


In general, if you are having trouble getting logged into ONTYME II, or having 
trouble with the command formats, you should contact Mac tech support at (498) 


973-2282. 
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Error Messages 


ONTYME COMMAND REFERENCE 


August 23, 1982 


Telephone number of Ontyme: 


All commands are preceded by : (colon) 


:IN This checks the mailbox for any messages. Messages are listed 
in order of the oldest message first. 


:IN OLD This lists the messages for the last 14 days that have al- 
ready been read. 


:0UT This lists any messages sent that have not been read by the 
recipient. 


:0UT OLD This lists the messages for the last 14 days that have already 
been read by the recipient. 


:READ This reads the message in the mailbox. If there is more than 
one message, than the oldest is read first. 


:READ ALL This reads all messages in the mailbox. 
: CANCEL Use this command to cancel a message. Type :CANCEL (#). 
:SEND This command followed by the mailbox sends a message. 


:SEND CC This command followed by mailbox(es) sends a message with 
carbon lists attached. 


:SEND RUSH This command followed by mailbox(es) sends a message immed- 
lately to recipient(s) who have available dial-out stations. 


:GET Retrieves a message recently sent or received via your ID, 
if the message is still on one of your in or out lists. 


:TYpe Type displays the text in your workspace. 
: ERASE Deletes all text in the workspace. 
: KEY Initiates the change-key (password) prompt series. 


NOTE: This display is available on the EMS by issuing the command 
: READ(s)®*(s )COMMANDS 


For more information on the EMS, try: 
:READ ** HELP 
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1) 


2) 


3) 


4) 


5) 


Using Access /// (Revision 2) on the EMS 


Before you log into the electronic mail system, you should have your 
message(s) created and stored on disk ready for sending. At this time 
boot Access ///. When you see the first uenu, select terminal anode, 
then press return, and you will see only a cursor on the screen. Now 
place a call to the local TYMNET office and follow the instructions 
on page 7. 


You must set up a recording file for your message to be stored. 

to do this press OPEN-APPLE S. Select “Change the recording file" 
with the up/down arrows and press return. Access /// will ask for the 
file name, or the new file name if you are changing the recording file. 
I£ you are operating at 39@ or 1200 baud and want to use a Silentype as 
the file it would be ".SILENTYPE". If you want to record to disk, name 
the file with the path first then the name (i.e. .D2/EMSLOG) and the 
message will be recorded to disk. When saving messages to disk, you 
may want to change the recording filename to avoid writing over 4 
previous message. 


To record to disk or (Silentype), you must turm on the recording file 
by typing OPEN@-APPLE R. The cursor starts flashing. The message will 
be sent to the recording file. After the message is recorded you must 
turn off the recording file so that the message buffer in the Apple is 
cleared. To close the recording file press OPEN-APPLE R again, just as 
you did to turn it on. You now see that the cursor is not flashing. 
Follow the "mail management" instructions on checking your mail box for 
messages and reading messages. 


To send message(s), return to the Access /// sat up mode by pressing 
OPEN@APPLE S. Use the up/down arrow to select “Exit terminal mode" and 
press RETURN. Select "Transmit a file” and press return. Enter the 
pathname (i.e. ".D2/Apple") for the file to be sent. Access /// now 
asks for delay parameters. The following normally work satisfactorily: 


line delay (er) 


character delay 8(cr) 


After transmitting the message, Access /// responds “File transmission 
complete’. To return to terminal mode press up artow twice and then 
RETURN. If you put the :SEND command at the end of the message you 
should see a message number. It's a good practice to writa these down, 
in case you need to refer to a specific message again. Eater the send 
command now, followed by return if you did not embed it into your text. 


After sending and receiving all mail, log off ONTYME II (refer to 
page 8). 
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1) 
2) 
3) 
4) 


Using Micro-Courier on the EMS 


Load Micro-Courter 
When the main menu appears, type "1" and press RETURN. 
When the editing menu appears, type "1" or "2" and press RETURN. 


Prepare or edit your messages using the correct format (see page 2). 


NOTE: More than one message can be prepared per file using Micro-Courier. 


5S) 


6) 


7) 


19) 


12) 
13) 


14) 


15) 


The important thing to remember is not to forget the send command 
after preparing each message. 


After message(s) have been prepared and edited, press the ESC key. 

Micro-Courier will ask for file name. 

a) Type month day/message # (use the first msg#) 
example: MARG1/9@1 

b) After typing the file name, press RETURN. 

Micro-Couriler will ask which drive to store file. 

a) Type either "1" or "2" (in most cases it is "2") 

b) Press RETURN. 

Press the ESC key to leave storage area. 

Press the ESC key again to go back to main menu. 

Type "6" and press RETURN. 


Type "1" and press RETURN. Micro—-Courier will ask for phone 
number. Type the local TYMNET number. 


Type "3" and press RETURN. Type "6" and press return key. 

Type "7" and press RETURN. 

Type "5" and press RETURN. Micro-Courier will ask for out file 
mame. Type name created in step 6. After typing file name, press 
RETURN. Micro-Courier will ask which drive; type the same number 
as in step 7, then press RETURN. 


Type "6" then press RETURN. Micro-Courier will ask which 
file name will store incoming traffic. Type month day/in msg#. 


example mar@l/in@@1 
Press RETURN. Micro-Courier will ask which drive will 


store messages. Indicate either 1 or 2 and press RETURN. 
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16) 


1a) 


19) 


29) 
21) 


22) 


Using Micro-Courier on the EMS 


Connecting to EMS 
a) Type "1" and press RETURN. 
b) Log in to TYMNET/ONTYME (see page 7). 


¢) When you have logged onto ONTYME/and have received the "accepted" 
acknowledgment, type “:LOAD ON” and press RETURN. 


‘dow to send 


a) When you have received the accepted acknowledgment press the 
ESC key and "T" key. Micro~Courier is now sending the out 
file to ONTYME. 


b) As messages are accepted, ONTYME will send message numbers back to 
you which will show on screen. 


How to receive 
a) Once sending has been completed, you can receive incoming 
mail. Press the ESC key and "R" key. This tells Micro-Courier to 


store all nessages received in the file that was aamed in step 15. 


b) Type ":READ ALL" and press RETURN. ONTYME is now 
sending your incoming mail. 


After sending and receiving mail, log off ONTYME (refer to page 8). 

Prass ESC and "E". Type "4" and press RETURN. 

Type "8" and press RETURN. Micro-Courier will go back to main menu. 
How to print incoming messages 

a) Type "1" and press RETURN. 

b) Type "2" and press RETURN. 

c) Type same file as was indicated in step 15. Type drive aumber. 

d) Press ESC key. 

e) Type "3" and press RETURN. 


f) When printing has been completed press =SC. Micro-Courter 
will go back to main menu. 


Type "8" and press RETURN. 
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Listing af TYMNET access numbers sorted by state, 3/1/83 


H, M, L, 1 = High, Medium, Low, Jnternational capacity 
T= 360 baud only, 300/1200 baed otherwise 


State 


RERR 


Phone Type 


205-432-3382 
205-834-3410 
205-882-3003 
205-942-4141 


ALASK 907-278-3511 
ALASK 987-586-6611 


ELELLLSSSSSSSSSSSLSLSSSSSSSSSESSSSESSSSESRRBE 


301-372-5780 
301-782-3210 
602-254-5811 
602-790-0764 
209-268-121! 
209-577-5602 
213-203-9865 
213-280-1103 
213-331-354 

213-365-2013 
213-435-7088 
213-518-3773 
213-572-0999 
213-574-7636 
213-574-8834 
213-577-8696 
213-865-0555 
213-906-8450 
213-986-9503 
213-998-0461 
213-998-3331 
408-426-8400 
408-443-4333 
408-980-3100 
415-462-8900 
415-490-7346 
413-778-3420 
413-785-3431 
415-798-2093 
415-836-8700 
413-932-0116 
415-966-8550 
415-986-8209 
619-296-3370 
619-320-0772 
619-485-1990 
619-727-6013 
707-575-0140 
714-370-1200 
714-498-3130 
714-462-0490 
714-662-0490 
805-324-2653 
805-486-4811 


& Ww 


SECAPZFAZSFZFSRRSSSSAIGAAAIASSSS 


TLL 


KAN 


805-482-9641 
916-448-815! 
203-475-2121 
303-830-9210 
203-227-7189 
203-242-7140 
203-367-402! 
203-755-1153 
293-789-8579 
203-965-0000 
783-442-3908 
703-442-3968 
703-691-8200 
703-734-3900 
302-429-0112 
302-478-0449 
305-467-3807 
305-424-7900 
305-627-5410 
305-725-8011 
305-851-3530 
813-535-4441 
904-252-448! 
904-434-9134 
904-721-8100 
912-236-1904 
912-392-7259 
208-343-4404 
217-753-7905 
309-473-2156 
312-346-4961 
312-368-4607 
312-368-4700 
312-438-5003 
312-790-4400 
815-233-585 
815-398-4098 
219-233-4163 
219-424-5162 
219-769-7254 
219-836-5452 
317-662-1091 
812-425-5211 
319-233-9227 
319-324-7197 
319-354-7371 
319-363-2482 
515-277-7752 
515-753-0667 
316-265-1241 


ASSEEPSSESSSS RAAT 


BERHSSASASAFSSESSSSS 


913-233-! 682 
913-384-1544 
502-499-7110 
686-253-3463 
318-237-9580 
318-488-4466 
304-291-2650 
304-524-4371 
413-781-4830 
616-482-5405 
617-482-4677 
617-482-7035 
617°755-0916 
301-347-8100 
301-778-1480 
207-774-2654 
317-487-2040 
616-385-3150 
616-429-2568 
616-459-5069 
616-723-8373 
616-775-1261 
616-946-0062 
313-459-8900 
313-569-8350 
313-465-2626 
313-963-3388 
317-787-9461 
612-339-5200 
601-769-6502 
601-944-9840 
314-421-5110 
314-731-2204 
314-875-1290 
417-782-3037 
417-831-5044 
816-232-1897 
913-384-1544 
406-494-4637 
704-376-2545 
919-323-4202 
919-379-9470 
919-549-8952 
919-725-9252 
919-832-1551 
919-885-9171 
402-397-0414 
402-475-8659 
782-293-9300 
702-882-7810 


SECO REET ROSE K SEO RZEBESBESEA OU EO RFREBERZBE BHAA BTEOIZBHRZzEH 


BPBPBBPEPESSRARLVYSLKLLVSRRARRARRARARARARRFZLFLFEEEFTFE REE 


603-423-8855 
603-882-0435 
603-893-6200 
201-432-0792 
201-460-9160 
201-483-5937 
201-785-4480 
201-894-8250 
201-781-1900 
689-235-3761 
409-452-1018 
609-452-1018 
305-843-6301 
212-269-9642 
212-332-0437 
212-685-4414 
212-785-5400 
915-437-7111 
516-549-2780 
516-872-4500 
518-463-311! 
607-257-6601 
607-962-4481 
716-248-8000 
716-285-6691 
716-845-6610 
914-328-9589 
914-471-4100 
914-684-4875 
216-535-1861 
216-744-5326 
313-223-3847 
513-489-2180 
419-243-3144 
614-421-7270 
405-947-4387 
918-582-4433 
503-226-9627 
503-399-1453 
215-269-9861 
215-337-9900 
215-432-1500 
215-666-9190 
412-765-1320 
717-233-8531 
717-846-3900 
814-946-8888 


PUERT 809-792-5900 
PUERT 809-933-4535 
PUERT 809-840-9110 
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401-273-0200 
803-252-0840 
803-271-2418 
803-271-9987 
803-577-2179 
803-585-2637 
615-367-9382 
615-637-3118 
615-736-5856 
901-529-0170 
214-263-4581 
214-638-8888 
214-758-1756 
512-225-6002 
512-444-3280 
512-883-8050 
713-427-5856 
713-632-2589 
713-975-0500 
713-977-4080 
806-762-0136 
919-533-1453 
915-543-3745 
915-683-5645 
881-364-0780 
703-345-4730 
703-491-8200 
804-528-1903 
804-596-7609 
804-744-4860 
804-744-4840 
804-872-9592 
802-458-2123 
206-285-0109 
206-473-7810 
206-754-3900 
206-825-4576 
509-375-3367 
509-747-4105 
414-235-1082 
414-437-9897 
414-432-3006 
414-722-5580 
414-735-9390 
414-785-1614 
608-221-4211 

304-522-3261 
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SAD MACINTOSH ICON 
OCT 26, 1983 


ty Kerye r\ 


Here is a example: 
Power on the Macintosh, holding down the NMI button on the left side of the 
computer. The sad Macintosh will appear, with a set of numbers under it. 
This set of code can be divided into two types of code. 


OF O0OD ~ Sub Codes 
| 


Class Codes 


Class Codes deals with the initial diagnostic code. 


1 = ROM test failed meaningless 

2 = Memtest ~ Bus subtest bits set corresponds to suspected bad RAM chips 
3 = Memtest ~ ByteWrite . ro 
4 = Memtest ~ Mod3test i , 
5 = Memtest ~ Addr uniqueness . . 


Class Code F = exception, only after diagnostics have passed. 
This is where the Sub Codes come in. 


F = exception 0001 Bus error 
0002 address error 
0003 illegal instruction 
0004 zero divide 
0005 check instruction 
0006 trapv instruction 
0007 privilege violation 
0008 trace 
0009 line 1010 
QOOA line 1111 
OOOB other exceptions 
0O0OC nothing 
OOOD NMI 


Another test to see how this works is, remove a RAM chip. Power up the Macintosh. 


A new code should appear under the sad Macintosh icon. When I did it, I picked 
the one closes to the Keyboard connector. The code under the Macintosh was 
028000. So number 2s class code tells me that it suspects bad RAM chip. The 
eight tells me that its the 15th RAM chip. 


RAM Chip # Code under Macintosh 


0001 
0002 
0004 
0008 
0010 
0020 


UP WNYe O 


6 = 0040 
7 = 0080 
8 = 0100 
9 = 0200 
10 = 0400 
ll = 0800 
12 = 1000 
13 = 2000 
14 = 4000 
15 = 8000 


This is a good example of just one RAM chip being bad, but what is there are 
multiple RAM chips that are bad? Try taking the 15th and 14th RAM chips out. 
the Code appears like this. 02C000, we can say since we know the code is in Hex 
that there are 16 possibilities. 


0000 
0001 
0010 
0011 
0100 
0101 
0110 
O11L 
1000 
1001 
1010 
1011 
1100 meaning the 15th and 14th chip is bad. 
1101 
1110 
1111 
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This is just a start to understanding what all the codes mean. If we try to keep 
a list, we should come across all the possibilities. 


.) 


SCysmgr 
CContrast 
D(evice 


MCount 


OC ff 


P(rinter 


U(nmount 


Work 


A(pple 
F(lip 


dI(m 


L(isa 
scR(een 
SCet Time 
T(ime 
V(olume 
Z(ero 


QCuit 


System Manager 
Set the contrast of the screen using < and >. 
List all mounted devices. 


Mount a Device 


&l = upper drive 

&2 = lower drive 

&3 = built-in parallel port 

&4 = lower connector on parallel card in slot 2 
&5 = upper connector on parallel card in slot 2 


turn machine off 


Mount Printer 
Serial printer presently is not supported 


Unmount a Device 

Set working Device 

It must have a volume named Lisa and all necessary 
system files. It may be set to the Monitor 12.2 Boot 
fileware by specifying the drive that it is in. 

At that point, all system software will execute off the 
fileware. 

Do not use 


Do not use 


Set the delay in seconds before the screen fades. The 
count is reset if a key is pressed or the mouse is moved. 


revision level of your machine 
Do not use 

affects the hardware clock 
displays the time 

set the beep volume 


remove all volumes on a device 


d 


Ci) 


Monitor filename syntax and file structure: 


File containers are called devices. A disk drive and a ProFile are each 1 
Device. All of the devices that the system is aware of are listed with the 


S(ysmgr command D(evice. 


Each Device has a name which ends in a slash '/'. Each has a number associated 


with it which is prefixed by a and-sign '&'. 


&l = upper drive 

&2 = lower drive 

&3 = built-in parallel port 

&4 = lower connector on parallel card 
&5 = upper connector on parallel card 


The device contains one or more volumes. The volumes on a 
with the F(ilers vM(nger command L(ist. All volumes known 
be listed with the F(iler command O(nline. 


Each Volume has a name which ens in a colon ':'. Each has 
with it which is prefixed by a pound-sign '#'. 

#5 = the primary volume 
Disk volumes may be #4 (special), #5, #13..#20. 


Each Volume contains files. A fileware volume can contain 
is stored sequentially on the volume. The space for a new 


in slot 2 
in slot 2 


device are listed 


to the system can 


a number associated 


77 files. Each file 
file thus must be 


sequential. After a large number of new files are made, it is necessary to 
use the F(iler's K(runch command to regain the fragmented volume space. 


ROM 7.0 


ROM 7.0 MacsBug Summary 


To use MacsBug, include it on your Mac diskette. The system will say "Macs Bug 
installed' when the diskette is booted. You may also include the Disassembler 
in the same manner. 


The Mac's modem port should be connected to another computer or terminal 
running at 9600 baud, no parity. Press the interrupt switch after booting the 
disk. The mouse should freeze and no error message should appear. On the 
terminal, a register dump should appear, and an asterisk '*' prompt. 


Commands available: 


DM Display Memory DM 100 100 DM RA7,-10 20 
SM Set Memory SMO 123456 SM 0 'ABCDE' 
D# Display/Set data register # DO OOOOFFFF 
At Display/Set address register # AO 
SR Display/Set status register 
PC Display/Set program counter 
US Display/Set user stack (normally A7) 
ss Display/Set supervisor stack (normally A7) 
BR Display/Set break points BR 
(up to eight) BR 4DD0 552A 
BR CLEAR 
A Display all address registers 
D Display all data registers 
TD Display all registers 
cV Convert between base 10 and 16 CV S$FDEF 
(all arithmetic is 32 bit) CV &65536 


To do hexidecimal addition, use CV Snuml ,num2 
To do hexidecimal subtraction, use CV Snuml,-num2 
To do hexidecimal negation, use CV $-numl 


G Go (continue) G 
(start at 44D0) G 44D0 
(continue until PC = 55EA) G TILL 55EA 
T Trace T. 17 
AT Trace Traps (traces all traps) AT 
(trace GetNextEvent ) AT 170 
(trace all Bit Traps) AT 158 15F 
(trace GetNextEvent in code 
block at 5000 - 53FF) AT 170 5000 53FF 


(trace all Bit Traps in code 
block at 5000 - 53FF) AT 158 15F 5000 53FF 


AB Break Traps same as AT, but breaks before executing trap 
HD Handle Display lists all allocated handles HD 
AD Data Break AD 158 15F 5000 53FF 
A simple checksum is calculated for the specified memory range. 
As each Trap is encountered, the checksum is recalculated. 
If the checksum differs, the debugger breaks. This call must 
be made with all four arguments. 
AX Cancel Break AX 


Clears the current AT, AB, AH, AC, or HS command 


Disassembler Calls 


IL List IL 4DD0 
lists the next 20 instructions IL 

ID List One ID 4DD0 
lists one instruction ID 


Debugger Notation 


/ Command Separator SM PC 4E71 / G 
. Last Address 

(for DM, SM, IL, ID) . DM . 100 
P Offset DM .,100 100 
RA# Address Register DM RA7,-10 20 
RD# Data Register SM RAO, RD2 


Advanced Debugger Calls 
AH Heap Break AH 158 I5F 


A heap check is made as each specified Trap is encountered. 
If $1A3E8 = 0 then the applzone is checked. (default) 

If S$1A3E8 <> 0 then SysZone is checked. The trap range must 
be greater than $2E. 


An error returns: Bad Heap at Al A2 where: 
Al = the previous block pointer 
A2 = the bad block pointer 


co” 


Pai 


HC 


Heap Check HC 


This call checks the heap as described in AH. An error is 


HS 


MR 


returned if any of the following conditions are true: 


The block size is past the top of memory 

The block size is odd 

For tree blocks, the next link is negative or past the top of memory 
For tree blocks, the previous link is negative or past the top of memory 
For rel. blocks, the back pointer is odd 

The heap base + back pointer is past the top of memory 

The heap base + back pointer do not point to the right master pointer. 


Heap Scramble HS 
If the traps NewPtr, SetPtrSize, NewHandle, SetHandleSize, HandleZone or 
ReAllocHandle are encountered, the heap is scrambled before executing 
the trap. It also preforms a heap check before scrambling on all traps 
> 30. 

Magic Return MR 

This assumes the first word on the stack is a return address generated 
by a BSR or JSR. It substitutes a break point for the return address. 


The execution continues until a break occurs. Then, SR is restored. 


This is not nestable. All other break point commands are still active. 


Known Problems 


It is a good idea to initialize DM and IL. DM 0, and ID PC, for 
example. 


DM RA5, as example, intermittently generates an address error. 
To fix, explicitly type the address in register. 


SM PC 4E71, for example, makes the system respond unreliably if 
a trap or breakpoint was set at that location. 


AT, as example, returns a Line 1111 exception. To fix, reboot. 


PASCAL 
DEBUG 


Pascal Program Debug Strategy 


Use DM to determine where the program is in memory. Seven letters of each 
procedure and function will appear in the ASCII columns. (The first letter 
has its high bit set.) The user program usually starts about 4DD0. The 
mainline procedures and functions are first, followed by the units and 
external procedures and functions in the order that you link them. Each 
procedure or function name suceeds the procedure or function code. To make 
life easier, link your own units before linking ToolTraps, MemTraps and 
MacPasLib. 


If the program doesn't appear to work at all, find the address of the start 
of the program. It will be immediately after the name of the last procedure 
or function. 


If you disassemble at that address, you will see a LINK instruction for A6 and 
a LINK instruction for A5. These address registers are used by Pascal to 
locate all variables and procedural parameters. Global variables are 
referenced negatively off A5. Local variables are referenced negatively off 
A6- Procedural parameters are referenced with a positive offset from A6. 


ToolBox calls and other calls to unit-resident procedures and functions are 
made through JSR *+addr instructions. The table ToolTraps is linked to your 
program, and contains all of the actual calls themselves. 


If you are writing a Pascal program that uses the ToolBox, the first thing 
you probably do is: 


InitGraf (@thePort); 


This assembles into: 


LEA $FF1E(A5) , AO 
MOVE.L AO,A7 
JSR *taddr 


You should see this shortly after the LINK instructions. This establishes 
the beginning of your program. 


To find out where this program fails, interrupt the Finder. Set G TILL addr 
where addr is the beginning of your program. Restart your program. If the 
program breaks sucessfully at that point, continue to use G TILL to selectly 
execute your program until it fails more spectacularly, or locks up. 


You will find that the 68000 code that the Pascal compiler produces is 
reasonably readable, and that the compiler produces smart code. 


To complement the debugger information, you may want to add debugging code 
in your program itself. One easy way to do so is to do WRITE s or WRITELN s 
to the .BOUT port. This information will appear on your debugging terminal. 
The code fragments required look like: 

VAR debug : TEXT; 

REWRITE (debug, '.BOUT'); 

WRITELN (debug, chr(10) {linefeed}, ‘This is a test’, 12345); 


WRITE and WRITELN support strings, chars, packed array of chars, integers, 
and booleans. 


{) 
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MONITOR 


The Monitor is an operating system for the Lisa computer. Its user 


incerface is patterned after that of the UCSD system on the Apple II. 
There are several possible system configurations. A standard one 
is: : 


jenn ———--—- + 
: Beats DEeueecer 
(or a hard| disk) | for j theo Basen 
| | Debugger | 
eee: sates 
| Bases aoe ie 
l | bed 
doe ewe ee we www ow oH HH LL 
| | | Ard 
| | wee ef eg = — 1, 4 
| | | | ‘ 
———---—-—_- ++ _ — - ae 
v | UART | | Corvus | | | 
faenneteeeh | | ee, oe | 
| Apple IZ |<= = -|-; LISA | | Profile | | Mac | 
| ec l — | 
$= -- | | | 
| en —_ 
v tet 
iccceeeneuah | -«sseee- 
| Soroe | | | Keyboard | 
| or | | a mee 
| Apple II | 
| monitor | | 


Not NESIZID 


en OTE 


The hard disk can be connected directly to the Lisa, or it can be accessed 
through the Apple II. It can also be omitted. 


BOOTING THE MONITOR 


~ 
. 


from a diskette based Apple II 
iskette in drive #4:. 


rh 
io 
"1 
1) 
mo 


the Apple II with 
the female boot in drive #5: 
and power up ¢n ¢ volume can also reside on a hard 
disk. SYSTEM.STARTUP boot volume automatically executes 

MONBOOT, the pro hat starts ut Sror on the Lisa. If you 

type space mug the boot process, MONBOOT 1 if 
CYP Cas 


? 
> 


che mal 


£ 
place tine Monte bey Ze Dise IN THe UPPER LISA 
Ses kine Teen THE System™ CNS, Naser Lisas Wrew 
ee ae AN 
= ‘as nN 
SHow -& MeMU SeeetMw [Oey REESS Pas Comm r 
Key. Roop ON THE Auta 91S 
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The Monitor comes up on the Lisa screen. If you want it to appear 
on the Apple Il monitor or the Soroc connected to the UaRT pert, 
change the MON.STARTUP program as follows: YO 


we 


l) Ber the Apple window: remove MON. STARTUP 


2) for the\Lisa window (the default); trans fez MONSTART1.OBJ 


we 
a 


: transfer MONSTART2.0BJ to MON.STARTUP 


3) for the UART win 


y, 
To move the Monitor around after booting, execute MOVESOROC. MOVESOROC 
simply asks you for the new source and sspeagsion for Monitor 1/0: 


A(pple, L(isa, or U(art. Agee always comes om the terminal to which 
output has been direct WRITELNs used for debiogging purposes appear 
on the Monitor screen; so you may not always want e application and 
Monitor screens to together on the Lisa. 


CONFiG.DATA set's the monitor how much RAM your system hass_ The default 
configuration assumes that you have a megabyte of RAM. For a 6K byte 
systen, CONFIG.DATA should -be a copy of NPC4.DATA. For a 512K Byte system, 
use NPC6.DATA. NPC16.DATA is a copy of the default CONFIG.DATA, itvcase 
you ever need to back up. See CONFIGURE in the Utilities chapter re 
wart to change CONFIG.DATA to suit your own needs. 
a 
The monitor’s keyboard driver supports the Lisa User Interface Keyboard 
layout. SHIFT Ts J is {, SHIFT ] is }, SHIFT . is >, and SHIFT , is <. 
“—-“ NMI is the key from the left in the upper row of the numeric 
keypad. Serratiiy —the Se key Ts nackspare . The CODE key is in the upper 
left corner of . keyboard. CODE ; is i, CODE + is ~, CODE _ \, and 


THE COMMAND LINE 


The Monitor command line is: 
Monitor: E(dit, Compile, F(ile, L(ink, A(ssemble, D(ebug, ? [0.1] 


There are several hidden commands. Type ? to see iio di isplayedt?” 


© 
a 


es = = be ogee 
USE TES OS ete EAL Lisa-style Editor x 

CCompile Pascal Compiler I-code generator —_ 

F(ile a-i: Filer Hebe, 

Baas E = ret Seer 

L(ink Linker 

A(ssemble Assembler 

Mie bo] ‘7 = = 

G(enerate Pascal compiler OBJ file generator 

ne SS See 

X(ecute Execute a program or an EXEC file 
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The } recognizes male volumes and logs them off-line so tbat 

they cannot be tally overwritten. The volume MSM s always 
available. MEMORY: allows to use the Lis S a file storage area. 
Of course, anything in MEMORY: is. aan che power is turned off, or 
the system is rebooted. MEMOBYe TS mounted as me #4:, and its defaule 
size ts 10 blocks. I Ze can be changed by the Z(e nd in the 
Filer, or bys 


When X(ecuting a program, che aonitor searches for the program filename 
as follows: 


Filename 

Filename.OBJ 

*Filename 

*®Filename.OBJ 

Filename.TEXT (* as an exec file *) 


When you invoke a program from the Monitor command line (F for Filer.Obj, 
for example), the Monitor looks first at the MEMORY: volume. 


EXEC FILES 


EXEC files can be used on the Monitor. They must be created in the 
Editor (there is no M(ake command). To execute such a file, 


X(ecute <filename> 


TZ an objece file exists with the same name as thac of the EXEC file, the 
object file is executed. The first character of an EXEC file (a textfile) 
defines the termination character. The first occurrence of two terminators 
marks the end of the EXEC file. Certain portions of the system (the compiler, 
for example) terminate an EXEC file if an error is encountered. If you 
X(ecute a .TEXT file, the monitor assumes chat the file is an EXEC file. 

EXEC files cannot be nested, nor can parameters be passed to then. 
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From o-To Description 4 
0000 OOFF Exception vectors (see 68000 manual) 
0100 OLFF Memory configuration aap (see page ##) 
0200 0300 © Free space for user assenbly globals 
0300 an -- 0341 KCS numerics status information ~ 
0342 O3FF Free space ~ 
6400 O7FF LisaBug Globals = 
0800 O8FF Boot stack 
0900 OAFF LisaGraf Globais 
OB00 OBxx Unit Table 
0co0 OCFF Pointer array 
ODOOd ODxx Syscom, miscinfo 
OEOO OEFF String buffer 
OFOO OF FF Unused (reserved) space 
1000 17FF User code buffer 
1800 3FF User Jump Table 
4000 Heap Botton 
Registers Description 
Al Stack Pointer 
Aé Stack frame Pointer 
AS Global Data Pointer 
Pebl A3-A4 Used for code optimization 
Rope A2=a0 Seratch 

DO=D3 Seratch 
D4=D7 Used for code optimization 
Registers D3 and A2 may someday be used by the compiler for code 
optimization. 

see NoT]E CN 

poe 
Rass é eves 
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POS DEVELOPMENT SYSTEMS GROUP 


Apple Computer Inc. © cr u 
a 


TO: Macintosh group 


Fred Forsman 2-P Ke Ys sed Ve Seer 
ee Now Correct } 


SUBJECT: New Pascal code generator for Macintosh 


Tne Lisa Pascal code generator has recently been updated with two new 
options. These options are activated by typing them on the “Input file? 
command line instead of the input file. The code generator will then 
re-prompt for the input file. 


SA+ Preserve registers A2 and 03 across procedure calls. 


H+ Perform Macintosh code generation. Automatically invokes $A+ 
vnen used. 


The Macintosh option performs three things. First, it inserts code, if 
necessary, in each procedure to preserve registers A2 and D3 across the 
procecure. This action is also activated by $A+. Secondly, the LINK AS, én 
statement at the beginning of main programs is forced to LINK AS, #0. 
Thirdly, the TST.¥ instruction at tne beginning of procedures and the TST.B 
instruction at the beginning of references to string parameters is forced 
to be eliminated. 


when $M+ is activated, the code generation process ends by displaying 
"MACINTOSH code generated.“ at the bottom of the display. 


This version of the code generator is availadle now from Andy Hertzfeld or 
myself. It is compatible witn (at least) version 12.2 of the Monitor. 
Earlier versions of the code generator cannot guarantee code that is 
compatible witn the Macintosh ROH. 
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MEMORY MAP 


A set of very detailed memory maps can be found in the Linker 
We give below a general view of memory and a detailed view of 
Monitor’s Map Table. 


—_—— ——— qe ne = 
| Memory \<2 -- 2-2-2 - =| UART | $lic 
| mapped | a ae ea 
| 1/0 |\<e7 ee eee =e | Port to Apple | $118 
$ewa == - -- -- > qeee nn --- == —_——+ 

| | 
een nner ie | | 
| Sereen | | += 
| Memory | +--- - | Memory Top | $114 
| | tenn 2 
Teseesse—s=S( se SS ens | Screen Base | $110 
| LisaBug | ae 
+ prea rae += - -| Buffer Pointer | S10C 
| Disassembler| | Seen as 
T= =< SeaSsS= Sor | | Not Used | $108 
| Graphics | | —-— = 
+ A SS SSS {- - =| Monitor Top | $104 
| Monitor | | er —+ 
bapa a a |~ ~ -| Monitor Bottom | $100 
| Code | | _-- ee Co 
| | <7 ee oo | 
| v | | 
sess ss== —<- - ee Default Stack Pointer | 
| Stack | \ 
| | | | 
| ov meee Wrenn | 
| rn | | | Assembly Globals | | 
| | | | —————— meena | 
| Heap | | Map Table at $l00|- - — 
team ne———a—e | | | 
| MEMORY: | | | 
www wn wn ee Hee =. Seta 
| Glotals | Trap Vectors | 


par tt tf nnn eee eee 
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THE MAP TABLE 


Monitor bottom 
Monitor top 


Buffer pointer 
Sereea base 


Memory top 
Port to Apple fi 
UART 


Per to Lisabug jump table 
Per to GOTOXY 

Per to Soroe driver 

Ptr to soft break table 
Per to UART driver 

Per to Corvus card 

Per to base of heap 
Defaule SP 

Per to user’s last A6 

Per to MEMORY: 

Ptr to Twiggy driver 

Per to hard disk Jump Table 
Per co debug card 

Per to loader for IUs 


Apple net 
Apple net 


Manual 


$100 
$104 
$108 
$10¢ 
$110 
$114 
$118 
$llc 
$120 
$124 
$128 
$12¢ 
$130 
$134 
$138 
$13C 
$140 
$144 
$148 
$14¢ 
$150 
$154 
$158 
$15C 
$160 
$164 
$168 
$16C 
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Many of these vectors can be changed by the CONFIGURE program described in 
the Ucility seccion of this manual. 


default stack pointer ($13C). 


change the default stack pointer value temporarily. 


The main vectcr of interest is the 
The utility program SETSP can be used to 


CONFIGURE can be 


used to change it permanently. Unused addresses are reserved for future 


use by the Monitor. 
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THE COMPILER 


Files needed: COMPILER.OBJ 
CODE.OBJ 
MPASLIB.OBJ, NOFPLIB.OBJ, or LUPASLIB.OBJ 


= 


GENERAL INFORMATION 


The compiler is split into two programs, COMPILER.OBJ and CODE.OBJ. 
COMPILER.OBJ (invoked by the Monitor’s C(ompile option) parses the 
Pascal program text into semantically equivalent tree structures. 
CODE.OBJ (invoked by the G(enerate command) then turns these trees 
into 68000 code. The compiler follows the proposed ISO standard 
Pascal with some exceptions and extensions. A complete definition 

of Lisa Pascal can be found in the Pascal Language Reference Manual. 
The definition of I-code formats and MPaslib information can be found 
in the Development System Internal Documentation. 


The compiler first asks for the 
Input file - 


The .TEXT extension is added, if necessary. In the following prompcts, 
the bracketed texe is used if you leave out that portion of the file names. 


Listing file (<cr> for none) - 
Output file [<input name>] [(.1] 
Debug file [<input name>} ({.D3G} = 


/ Tf you do not want a debug file created, type <ESC><exr>. <er> always 
accepts the defaule setting. If you write both the .I file and che 
-DBG file to the same volume, use che (*}] specification on the .I 
file to avoid space problems. The trouble arises when you have 

one large block on the volume. When the operating system allocates 
space for a file, it gives the file all of the largest block it can find 
unless you specify otherwise. Lf no other block of space exists 

and all of the existing block has been allocated to the .I file, 

you get a "no room on vol” error when the system attempts to 

open the .DBG file, even if there is plenty of room for both. The 
(*] specification tells che operating system to allocate only 

half of the largest available block cto che file. 


The Pascal run time support routines are in MPASLI3. If you do not 


need the floating point arithmetic routines, you can use NOFPLI3 
instead of MPASLIB. If you are using intrinsic units, use IUPASLI3. 
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COMPILER OPTIONS 


§C+ or SC = Turns code generation on (+) or off (=) on a procedure 
by procedure basis. The default is C+. 


$D* or $D= - If the $D option is on (the default), the compiler places 
procedure names in the objece file. The object file is 
slightly larger, but LisaBug use becomes much more 
pleasant. 


SDECL ~ Compile time variable declaration (conditional compilation). 
Compile time variables must be declared before they can be 
used (in SSETC), and all declarations must precede the 
first procedure or function definition in the program. 

The SDECL compiler option does not exist until the 
version 8.0 compiler. 


SE filename - Starts logging compile time errors as they are encountered. 
This option is analogous to the SL option. 


SELSEC ~ Conditional compilaticn. 
SENDC = Conditional compilation. 
SI filename - Includes the file ‘filename’ in the compilation. The 


filename cannot begin with a ‘+’ ora ‘=’. 
SIFC = Conditional compilation. 


SL filenanze ~ Starts making a listing of the compilation in file 
‘filename’. If a listing is already in progress, that 
file is closed and saved before the new listing file 
is opened. 


Ler or S$L=-—-= - The first +/- turns listing on (+) or off (=) during the 
first pass. The second +/-, if present, turns on or 
off the listing with objecc code offsets during the 
second pass. The third +/-, if present, controls 
the production of an interlisting during the second pass. 


SR+ or S$R- - Turns range checking on (+) or off (-). Currently, 
Tange checking is done in assignment statements, on 
array indexes, and for string value parameters. The 
default is $R+. 


$S segment - Starts putting code modules into the segment named 
“segment’. The default segment (’ “) holds the 


main program and all built-in support code. All other 
code can be placed in any segment. 


SSETC ~ Compile cine variable declaration and assignment. 


$U filename - Searches the file ‘filename’ for any subsequent units. 
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$X+ or $X- ~ Turns stack expansion code on (+) or off. The defaule 
is $X+. 
S£+ oF Sh ~ Allows the use of percent signs as legal characters 


in identifier names. The default is $%-. The % option 


should not be used by normal applications. 


PACKING INFORMATION 


Packed records are very expensive in terms of the number of bytes of 
code generated by the compiler to referance a field of a packed 
record. In general, you should avoid packing records unless there 
are many more instances of a particular record than there are 
references to it. 


Packed arrays are also code-expensive, with one exception. Packed arrays 


of char are treated as a special case, and the code associated with 
them is compact. 


To paraphrase von Neumann, anyone who needs to know the details of 
the packing algorithms is in a state of sin, but the following is 
provided for the sake of completeness. 


Elements of packed arrays are stored with multiple values per byte 
whenever aore than one value can be fit into a byte. This only 
happens when the values require 4 bits or less. Values requiring 
3 bits are stored into 4 bits. 


The first value in a packed array is stored in the lowest numbered 
bic position of the lowest addressed (most significant) byte. 
Subsequene values are stored in the next available higher numbered 
bic positions within thac byte. When the first byte is full, the 
same positions are used in the next higher addressed byte. Consider 
the following exazples: 


a: PACKED ARRAY(1..12] OF BOOLEAN 


byte Ll: bic 0 
| a8 | a7 | a6 | a5 | a4} a3 | a2 | al | 
+ 


——<—= 


byte 2: 

Ss - - — 
| oo Unused -- {} al2} allj alO| a9 | 
-—_-_-_-——--— OOo oe eee 
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b: PACKED ARRAY[3..8] OF 0..3 


byte l: 

mad 
i; af6) } af{S} 1) af4] | al3) | 
ape te ae ep pare oe ene eee a 
byte 2: 

pew eh © aap pee oe See war ecane 
| == Unused -== | af8] | af7] | 


¢: PACKED ARRAY(0..2] OF 0..7 
or 
PACKED ARRAY(0..2] OF 0..15 


| oo Unused —— | a(2] | 
a 


You can use the @ operator to poke around inside any packed value 
and thereby discover what the packing algorithm (probably) is. For 
example, to get the data given above, you can use a program like 
the following: 


Program Test; 

Var i:integer; 
p: “integer; 
boolArr:packed array [1..12] of boolean; 

Begin 

boolarr({1l]:=*true; (* find out where lst bie is put *) 

for i:#2 to 12 de boolarr[i]:=false; 

p:=@boolarr; 

wWricteLa(’equiv word is 


’ = 

»P)3 
(* write the packed array as an integer *) 
End. 
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Consider also the following program fragment 


BITE = 0..255; 
WORDSWAP = PACKED RECORD 
CASE INTEGER OF 
O:(HWord: INTEGER); 
1:(HiByte,LoByte:3ITE); 
2:(High:S3ITE; 
Low: BITE); 
3: (Hexl,Hex2,8ex3,Hex4:0..15); 
4:(Bool:0..1; 
Oeel ,0cee2,0¢e23,0cr4,0e25:0..7); 
53 (Al30.<15; 
BL:0..7; 
B2:0..7; 
B3:0..73 
B4:0..7); 
6:(Bin:PACKED ARRAY(0..15] OF 0..1) 
END; 


Each variant gets packed into 16 bits. The question then is, where in 
the 16 bits do the various portions of the variants get placed: 


[15 0} Integer 

es a 

| HiByte | LoByte | HiByte,LoByte:0..255 
a F 
| High | Low | High:0..255; Low:0..255; 
tt 

| Hexl | Hex2 | Hex3 | Hex4 | Rexn:0..15 

San oe er 

[B\Ocel |Oce2 | Oce3 1Oee4 [Oce5 | B:0..1; Octn:0..7; 


| Al } BL | B2 | 33 | Bo | Al:0..15; 3n:0..7; 


1716151413121 1/O/FIEIDIC/BIAI91 8] Variant #6 (using hex digits) 
OO 


> 
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LISA PASCAL AND APPLE PASCAL 


Lisa and Apple Pascal are quite similar. We give below a list of the major 
differences, and a section of hints for translation from Apple to Lisa 
Pascal. Full details can be found in the Pascal Language Reference Manual. 


EXTENSIONS TO APPLE PASCAL 


@ Operator 

CASE OTHERWISE Clause 

POINTER function 

fexadecimal constants 

DISPOSE 

ORDS funetion 

Global GOTO 

Parametric Procedures and Functions 


DELETIONS FROM APPLE PASCAL 
Initialization block in UNIT declaration 
PWROFTEN, TREESEARCH, BYTESTREAM, WORDSTREAM, KEYBOARD 
Extended comparisons 
Some Compiler options 
SEGMENT Procedures and Functions 
REPLACEMENTS FOR APPLE PASCAL FEATURES 
Long integers == 32 bit integers 


Scan =~ ScanEq and ScanNe 
TURTLEGRAPHICS and APPLESTUFF -=- LisaGraf 


TRANSLATION FROM APPLE PASCAL TO LISA PASCAL 
Translation of Apple Pascal programs is usually not very difficult. The 
following hines may be of use to you if you find yourself saddled with 
che translation task. Thanks to Ken Friedenbach for the hints! 
MOVELEFT(Source_Buf(i],Dest_Buf{k],n) can be translated into: 
FOR Locali:=0 TO n=l DO Dest_Buf[Locali+k]:=Source_3uf[{Locall+i]); 
Ie may be necessary to declare the local integer used as the FOR loop 
control variable. 
MOVERIGHT(Source Buf[i],Desct_Buf[k],n) becomes: 


FOR Locall:sn-1 DOWNTO 0 DO Dest_B8uf[k+Locall] :*Source_Buf[i+Locall]; 


i 16—Fean—a? 
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FILLCHAR(Buf({i],a,Ch) becomes: 


FOR LecalI:=0 TO n=l DO Buf(itLocall]:=ch; 


L:=SCAN(n, Och,Buf(k]) becomes: 
Locall: #0; 
IF n>0O THEN : 
WHILE (Locall<n) AND (Buf(k+Locall]=ch) DO Locall:=Locall+l 
ELSE 
WHILE (Locall>n) AND (Bui(k+Locallj=ch) DO LocalI:=#localI-1; 
1:=Locall; 


If SCAN {fs looking for =ch, just substitute <>ch in the loops above. 


READ(KEYBOARD,ch) becomes: 


UNITREAD(2,ChaArr,1); 
eh: =ChaArr{0]; 


where chArr=packed array [{0..1] of char. 


EOLN( KEYBOARD ) 


can check the character read above. If ch=CHR(13) then EOLN is true. 


KEYPRESS 


ts NOT UNITBUSY(2). 


Strings aust be given a length, non-local EXITs aust be replaced with GOTOs. 


ClearScreen and ocher such funccions can be handled bv Jim Merrice’s 
CUSTOMIO unit. ClearSereen on the Lisa is presently WRITE(CHR(27),CHR(42)); 


If underbars are used in the Apple Pascal program, they must be used 
consistently (chey are ignored by the Apple Pascal Compiler!). 


If the Apple Pascal units have code in the inetalizacion block, put ic 
in a procedure called at the beginning of the progran. 
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To force segments to be resident, build a chain of dummy procedure calls 
that forces the loader to keep them ail in core. The main program then 
becomes 2 procedure called by the top of the chain. Say we have 3 segments 
called SEG1, SEG2, and SEG3, and have put our main program into a procedure 
named MALN_PROGRAM. Wwe can now force everything to be memory resident by 
adding the following procedures: 


(*§§ SEG1*) 

Procedure Kiudge3; 

BEGIN 

Main _Progran; 

END; : 


(*§S SEG2*) 
Procedure Kludge2; 
BEGIN 

Kludge3; 

END; 


(*SS SEG3*) 
Procedure Kludgel; 
BEGIN 

Kludge2; 

END; 


(*sS *) 

BEGIN 

Kludgel; 

END. (* end of main program *) 
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THE LINKER 


Files needed: LINKER.OBJ or IULINKER.OBJ 


GENERAL INFORMATION 


The Linker combines obdjece files. ts input consists of commands and 
object files. Its output consists of object files, link-map informacion, 
and error messages. Partial links are allowed. The output of the 
compiler mist be linked with some version of PASLIB.OBJ before ic 

can be executed. Other objece files, including libraries, partial 
links, and object files produced by the Assembler, can also be linked 
into che output objecc file. 


The Intrinsic Unit Linker (IULINKER.OBJ) expects to find the file 
*INTRINSIC.Li3 even if you are not using any intrinsic units. LINKER.OBJ 


(‘The Linker’ in this chapter) expects to find LOADER. IMAGE somewhere 
on the systen. 


LINKER PROMPTS 


The linker first prompts for the names of the input files: 
Input file [.0BJ] - 


It continues to ask for input files until you type <cr>. The 
next requese is for che 


Listing file - 


Type <cr> if you don’t wane any listing file. The last request 
is for the name of the 


Outpue file [.OBRJ] = 


The Linker can read commands from a text file. At any tine 

you can switch to such a file by typing “<’ followed by the name 

of the file in which the commands reside. If there is a blank line 
in the file, the. Linker assumes that this line is equivalent to the 
<er> typed to end input file input. The line after the blank 

line (if any) is the listing file name, and the line after 

that is the output file name. These two files need not be 

given in the command file. 
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LINKER OPTIONS 
Linker options can be entered at any time in response to the prompt for 
an input file. The options do not have any effect until the link begins. 


In particular, segment names cannot be mapped to several different names. 


The Inerinsic Unit Linker has the following options: 


+4 Alphabetical listing of symbols. The default is -A. 
7D Debug informacion. The default is ~D. 
+H num +H sets the maximum amount of heap space the Operating 


System can give a program before allowing it to die. 
Here, as in the other options, ‘num’ can be either 
decimal or hexadecimal. 


-H num -H sets the minimum amount of heap space needed by a 
program. 


+L Location ordered listing of symbols. The default is -L. 
The location is the segment name plus offset. 


+M iromName toName 
+M maps all occurrences of the segment ‘fromName’ to the 
segment ‘toName’. This allows you to map several small 
segments into a single larger segment. You can thereby 
postpone che segmentation decision until link time by 
using many segment names in the source code. a 


+? Production link. The default is -P. +P produces a 
‘production’ .OBJ file. A production object file 
does not contain information used by the debugger 
and the linker, and intrinsic unit files do not 
contain a jump table. The production object file can 
be executed, but cannot be handled by the linker or 
the debugger. 


+S nun 
+S sets the starting dynamic stack size to ‘num’. The 
default is currently 10000. 
+T num 
+T sets the maximum allowed location of the top of the 
stack to ‘num’. The default is 128K. 
Prints the options available and their current values. 
The Linker has the following options: 


2 Prine out the options and their current values 


Use Quick Load blocks in place of Executable blocks. 
The Monitor has never supported this option. 


OO 
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P Do a Physical (+P) or Logical (-P) link. +? is the 
default. The logical link uses the MMU’s to map logical 

addresses into physical memory. ‘The physical link 

maps all of memory linearly. A logically linked program 

is more sensitive to uninitialized pointer problems than 

a physicaly linked program. If a physical link is 

‘performed, the linker and the executable program it 

produced must execute with the default stack 

pointer set to the same location. The default stack 

pointer value is $80000. 


THE LINKER OUTPUT FILE 


If no errors occur during the link, the output file contains the result 
of the link. If all external references are resolved and a starting 
location is specified, the output file is an executable object file. 
You must link in MPASLI3.0BJ or its equivalent to resolve all external 
references. 


ERROR MESSAGES 


The Linker reacts in three general ways to dubious usage. [¢t 
gives a warning message if some action cannot be performed. This 
kind of message can be distinguished from the others by carefully 
noting chat it begins with: 


e** Warning 


In order to recover from the error, simply reenter the command 
correctly, and all will proceed as though no error had occurred. 


An ertor that makes it impossible for the Linker to complete the 
link successfully causes a message that begins: 


w4* Error 


The link process can be continued, however, so that any further problems 
can be discovered. 


A fatal error causes the link to be terminated immediately and sends 
a message beginning with: 


wee Fatal Error 


See the section on errors for a complete list of the Linker error sxessages. 


ro 
oo 

0Q 
o 
_ 
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EXTERNAL NAMES 


An external name is a symbolic entry point into an object module. 
All such names are visible at all times--there is no notion of 
the nesting level of an external name. External names can be 
either global or local. A local name begins with a $ followed 

py 1 to 7 digits. No other characters are allowed. A global 
name ig any name which is not a local name. 


The scope of a global name is the entire program being linked. 
Unsatisfied references to global names are allowed. Only one 
definition of a given global name may occur in a given link. 


The scope of the local name is limited to the file in which it 
resides. When a partial link is done, global names are passed 
through to the output file unmodified, but local names are 
renamed so that no conflicts occur between local names defined 

in more than one file. All references to a given local name must 
occur within the same input file. 


MODULE INCLUSION 


The first file presented to the Intrinsic Unit Linker must be either 

a main program file to be linked, or an unlinked intrinsic unite file. 

You cannot have both intrinsic unit and main program files in a single 
link. All modules from a non-library file are ineluded in the output file. 
Only those modules which are needed in the link, however, are taken 

from a library file. The Linker considers a module to be needed if: 


1) it defines an unresolved global name, or 


2) it is referenced by a module in the same library file 
that is included in the output file. 


A module is not included simply because it references an already 
defined global name. Thus, the inclusion of a library module 

is dependent on the order in which files are specified to the 
Linker--che module must be specified after the modules that 
reference it. You can easily use an alternate module to one in 
a library by including the alternate prior to specifying the 
library file. 


After linking an intrinsic object file and before referring to it in 
another link, ypou must update the segment and unit tables in 
*INTRINSIC.LIB with the IUMANAGER utility. IUMANAGER is described 
in the Utilities Chapter of this manual. 


Page 18 


STRUCTURE OF AN EXECUTING PROGRAM 


When a program ts executing, the Lisa memory map is: 


= assesses SS SS = ($114) 
| Screen Memory | 
pss ee ees == <So-s = = = = ($110) 
| Bootfiles | 


| (LisaBug, GotoXY) | 
| (Core, MonSorec) | 


pm nnn ei ee ($104) 
| Monitor | 
oe 8g Hem nn nnn === wean ee me = ($100) 
| Program Code | 
CODE | | | 
| Vv | 
eco es | | 
| (Jump Table) | 
JUMP | (data pers ) | (see below) 
too--------------- m——<------ ($13¢) 
TABLE | pars to main prog | (see below) 
i ey 2etK-e 222-2 (45) 
| Globals | 
| | 
| Stack (grows down) | 
to ee ee ee ee POSS Se ae oe (A6) 
DATA | (Locals) | 
to ee ee ee eee io + 4 = = (A7) 
| | 
| | 
| Heap (grows up) | 
0 6 8g Hmm see se sean sor 
| MEMORY: | 
$—------------------ 
| Monitor heap | 
tenn ----- moaenKe ee ee ($138) 
| Jump Table | 
$  --- -- --- mea ee ee $1800 
{| Monitor globals | 
$= -------------- ee $0100 
| Excepction vectors | 
pre nrnie  e e e - $0000 
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(Top of memory) 


(Sereen Base) 


(Monitor top) 


(Monitor bottom) 


(physical link) 
(SETSP defaulc) 


(top of globals) 


(stack frame pointer) 


(top of stack) 


(Heap base) 
(logical link) 
(used to be A4) 
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A physical link places the Jump Table above A5, but a logical or Intrinsic 
Unie link places the Jump Table at $1800 to free up aé for code optimization. 
Even when placed at $1800, the Jump Table is logically above A5. The 
program globals are located below A5. The details of the portion of 


memory addressed by offsets from A5 is: 


fone oee woeceecos+ 
| Jump Table H 
$eee eon ween ows eenn a= ns 
mn | Inerinsie Unit | 
+ Data Per + JT SEGMENT 
| Table | 
° of ° 
+--. oa Units e 
| | | 
| o+ + 
oe | 
H perenne nooo sr oro— — 
| JTSegDelca | (distance to jump table) 
| Fr rr rr nnn nnn nn noa= —K2 se ce ($13¢) 
| | StkSegDelta | (distance to stack) 
| seecon= a<= wecoeey 
| | main program parameters| (see below) 
| wee ee ee ee eee Ke ----- (AS) 
| | Main program globals | 
| we eke ee ee eg we © -+ STACK SEGMENT 
| | Regular Unit globals | 
wee ee ee ee ee + 
- 


- >| Intrinsic Unit Globalis {| (Shared Intrinsic Unit globals are elsewhere) 


eo ce 


(a wee ee 


If the program is using shared intrinsic units, some of the intrinsic unit 
data pointers point to locations in the Shared Data Segment which contains 
global data used by all processes. The JT Segment is read-only and grows 


up. The stack segment is read-write and grows down. 


YO 
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The parameters to the sain program are: 


+ — nn 

| pointer to SS$FIRST | +58 
own nnn nnn 

| reserved | +56 
ern == + 

| Lisagraf info | +52 
’ eat a ee 

| Saved registers | 

ee —— 

| Monitor flag | +21 
| Physical Size | +20 
teen + + = 

| Common Size | +16 (regular and intrinsic unit size) 
a ee = 

‘| @OUTPUT {| #2 
teen ne on 

| @INPUT | +8 
+———---—--- -———-- ----- —_ 

| Return address | +s 
+ ——-----—------ — 

| Old AS | +0 
nr rrr aK = = = = -(45) 
| (Globals) | 


A6 is the stack frame pointer. The stack frame of a procedure is: 


High Memory pwn nn we 
| Caller’s stack frame | 
| Caller’s dynamic link \<- - 


| Funetion Result (only | 
| for a funceion) | 


| Statice Link (only for a | 
| level 2 or higher proc) | 


+ 
| 
| 

nnn nnn nnn nr nnn nn = | 
| 
| 
| 
| 
| 
| 
| 
| 


| Return Address | 


ewe - e© ew ew we ew ew ew ew = — 


(A6) - = - =->| Dynamic Link [== = 


~—| | = =§ = @& ge w= = = = —_— 


| Loeal frame | 


Low Memory en nr rn nr (a7 
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6:1 The Assembler... 252 2ccos cscs ceedewsscadccassevenweeetereeceseeess 6-3 
The assembler translates 68000 assembly language into machine language. 
G7 LS Ci PRE oo ins ooocsdecansecdctreceteosesesmsaesiaden 6-3 


The assembler accepts a text file es input, and produces a machine 
language (.OBJ) file as output. 


6.3 Assembler Opcodes .......2.2.c05 0200-2 esscebaceccccseesseess eee sssee< 6-5 
The assembler opcodes are the standard 68000 opcodes, with a few 
alternate forms for some instructions. 


6.4 Assembler Symtax ..... 2.2.2... e eee nee nn eee eee cence eee e eee ee enee 6-6 
An assembler statement consists of an optional label, the opcode, and one 
or two operands. The operands can contain expressions. 


6.5: PESEMDIET DITECCIVES 2c ooccscdeccccc ccsscsseccsteecctulesesssciccscseens 6-10 
The assembler directives provide for procedure and function definition, 
macros, label and constant declaration, listing control, storage allocation, 
and conditional assembly. 


6.6 Communication with Pascal ............222.2.-2-- 22 eee eee ee eee eees 6-17 
Assembly language routines can be either procedures or functions called 
from aPascal program. Perameters are pessed on the Pascal stack. 


6.7 Assembly Language Examples ......:..-----..-2..0c--sceccensseeeeeee 6-21 
This section provides example assembly language routines illustrating 
parameter passing and other functions. 
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The Assembler 
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THE ASSEMBLER 


The assembler is a program that translates assembly language source code 
into object code. The assembler accepts a text file containing the source 
code es input, and produces an object file as output. The object file 
produced must be linked with a Pascal main program before it can be 
executed. 


Assembly language routines ere used to implement low level or time 
critical functions. This chapter describes how to use the essembler, andthe 
syntax of assembly language programs. Information on the machine 
instructions available on the 68000 processor can be found in the Motorola 
MC68000 Reference Manual. 


6.2 Using the Assembler 
To assemble a procram, press A from the Workshop command line. Then 
specify the input file (the file that contains your source program) and two 
output files: an optional listing file and the object file (the file that contains 
the object code produced by the assembler). 


The input file must be a text file containing assembly language source 
statements. You can create this file with the Editor. The output file 
produced is an object file (.OBJ), that must be linked with a Pascal main 
program to be run. 


6.2.1 Assembler Options 
When you start the assembler, the option settings are displayed. You can 
enter the options selection mode by responding to the input file promot 
with "?". There are two assembler options: 


P Pretty Listing. 


$ Print information about available space. 
Each option may be set to + or -: 

+ On 

- Off 


When Pretty Listing is on, the forward referenced labels or offsets are filled 
in with the correct values. 


After setting options, press return, andthe assembler asks you for the name 
of the input file. The assembler then esks you for the name of the listing, 
and the output files. 


6.2.2 The Input File 
The input file is a text file containing assembler language source 
statements. Afile created using the Editor will be intext file format. 


workshop Liser's Guide for the Lise — The Assembler 


when the essembler asks you for the name of the input file, type "?" if you 
want to change essembler options at this time; otherwise type the 
pathname of your source file. 


6.2.3 The Object File 
The object file produced by the essembler contains 4 machine code version 
of your source program. The name of an object file ends with OBJ. Araw 
assembly object file is not executable; it must be linked with a Pascal 
program that calls it. See Section 6.6 for further information. 


The output file will be an object file which must be linked with a Pascal 
mein program before it canbe executed. 


6.2.4 The Listing File 
The listing file produced by the assembler contains 4 list of source 
statements and their machine-language equivalent. If Pretty Listing is off, 
all addresses for forward referenced labels will be displayed es asterisks 
("*). If Pretty Listing is on, the actual value will be filled in. 


Source statement errors are flagged in the listing. Refer to the Appendix 
for a list of assembler error messages. 


An exemple of an assembler listing file is shown in Figure 6-1. Figure 6-2 
shows the same file listed with the Pretty list option. 


PALL KE cocoeson; 
S$ saSqTR FILE: Xan STR. TEXT 


POSE = 

cosa, ores aenSer 

coos: 920SF eewvs. | a7), 0 + Petuer secress 

occa 2osF awe. | af je, ad ; eserese of string pessed free Pssesl agz 
cocoa 2FGA aove. | a2, °(a7) } Sewe sereter reg a2 

cose 

Coos: «SFA COIS ies Bize, af 

ceoe, 4286 elr.t 

cos isi2 aova. 8 (a2}, 6 : gee size ef string 

COGE) 

cosm isse aove. 5 (e2 +. (ad b> ; easy size ef sering (fiese Byte sf string) 
6ciG S340 easy see 2i, 00 } Gare cepying Bering? 

cSim éS0C SO05 sie esre ; yes, Peturn te sesce! 

0028 izbA move. 5 (a2 yo, (ad ; Seay ene sher of tire string 

Cola sore are ay 

cola 

CSlia 24F sence cove. | af ye, a2 } PEStere seratsr ~Ty 

scia 40 j= 26 } ; Peers te saeae| 

6326 . 

SGi&: 25 8.28 - Byte 3 

CIF, 74 88 69 73 20 73 74 «aySer + seeii “enim string is feem tre LSA sseems ier’ 

S26: 72 69 6E 67 20 $9 73 

CC2mh 20 6 72 SF GD 20 74 

SoO3@ $8 65 20 4 49 SO 41 

203m 20 61 73 73 6S 6 82 

c04m Gf SS 72 

304% «3S -alegr 2 : gst t@ Be Burs SeRt IMBtPUEtiSA is Sm sers 
0046: ; Beursary (even sesress ; 

00.46, 

S046; ene 


Assembler Listing 
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If you specify a device name such es -PRINTER or -CONSOLE for the 
listing file, the listing will be printed on that device. If you specify a disk 
file, the listing will be created as a text file; you may then print it by using 
the Copy command inthe File Manager command line. 


NOTE 
If you want pretty listing, the listing output must be sent to afile, not 
to adevice. 
pretty listing 
Figure 6-2 
Pretty Listing 


6.3 Assembler Opcodes 
The 68000 opcodes are described in the Motorola MC68000 Microprocessor 
User's Manual. The assembler has two variant mnemonics for branches 
(BHS for BCC and BLO for BCS). The variant names are more indicative of 
how the instruction is being used after unsigned comparisons. The default 
radix is decimal. 


The size of an operation (byte, word, or long) is specified by appending 
either .B, .W, or .L tothe instruction. The default operation size is word. To 
cause a short forwerd branch, append a .S to the instruction. The default 
branch size is Long. 


Note that the TAS instruction does not work on the Lisa machine. 
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6.3.1 Optimization 
Note that the Assembler accepts generic instructions ard assembles the 
correct form. The instruction ADD, for example, is assembled into ADD, 
ADDA, ADDG, or ADDI, depending onthe context. 


ROD D3, AS 
becomes ADDR D3, AS. 


MOVE, CMP, and SUB ere handled in asimiler manner. 


6.4 Assembler Syntax 
This section describes the form in which tne essembler expects an 
assembly lenquece program. The structure of an assembly language 
program is described in Section 6.4.1. Rules for forming constants, 
identifiers, labels, expressions, and addressing modes are provided in the 
following sections. 


6.4.1 Structure of an Assembly Language Procram 

An essembly language program contains one or more procedures or 
functions. The structure of an assembly language source file looks like 
Figure 6-3. The source file contains an (optional) section of operations that 
don't generate code. Constants or macros are usually defined here. Next it 
conains one or more procedures (.PROC) or functions (FUNC). These each 
contain @ sequence of code generating operations and directives. 4 
procedure or function ends when the assembler encounters the next PROC 
or FUNC. A .END directive is the lest staternent inthe program. Any text 
beyond the .END is ignored. 


fon COME Generating OPETElIions 


PROC (or FUNC) 
code generating operations and arn directives needed 


-PROC 
-FUNC 
ete. 
-END 


Figure 6-3 
Structure of an Assembly Language Program 
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The directives that don't generate code ere: 


-EQU .MACRO Rig JST -MACROLIST 
-ENODM ELSE -NOLIST -NOMACROLIST 
REF -ENDC PAGE -PATCHLIST 
-DEF HL -NOPATCHLIST 
6.4.2 Constants 


Constants inthe essembler can be either numeric or string constants. 


6.421 Numeric Constants 
Numeric constants in the assernbler can be expressed in decimal, 
hexadecimal, octal, or binary. The default radix is decimal Numeric 
constants are expressed es follows: 
Decimal 
Decimal numbers sre formed with the decimal digits (0-9). Examples: 
10 
13 
137 


Hexadecimal 
Hex numbers can be expressed intwo ways: 
1. Preceed the number with a"S". Examples of this are: 
$FF13 
$127 
2. Follow the number with an "H". Using this form, the number must 
start with a digit (0-9). Examples: 
OFF13H 
195H 


Octal — 
Octal numbers are followed by the character "O". Note that this is the 
letter O, not the number zero (0). Examples: 


770 
1040 


Binary numbers are followed by the character "B". Examples: 


10116 
111000B 


workshop User's Guide for the Lise 


64.2.2 String Constants 
String constants are delimited by matching pairs of single or double quotes. 


Examples of string constants ere: 


"this is astring constant" 
‘using single quotes as delimiters lets you include "double" quotes’ 


6.4.3 Identifiers 
Only the first eight characters of identifier names are meaningful to the 


assembler. The first character must be alphabetic; the rest can be 
alphanumeric, period, underber, or percent sign. 


Examples of identifiers are: 


LOOP 
EXIT_PRC 
NUM 
num64% 


6.4.4 Labels and Local Labels 
Labels begin in column one. They canbe followed by acolori, if you like. 


Local labels can be used to avoid using up the storage space required by 
reguler labels. The locel lebe] stack can handle 5O labels at atime. It is 
cleared every time @ regular label is encountered. A local label is an 2 
followed by astring of decimal digits (0-9). Examples of local labels are: 


6.45 Expressions and Operators 
All quantities are 32 bits long unless constrained by the instruction. 
Expressions ere evaluated from left to right with no operator precedence. 
Angle brackets canbe used to control expression evaluation. The operators 
are: 
unary or binary addition 
unery minus or subtraction 
ones complement (unary operator) 
exclusive or 
multiplication 
division (DIY) 
MOD 
logical OR 
logical AND 
equal (used only with .IF) 
> not. equal (used only with .IF) 


> -b + 


~ Wear 
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There is no operator precedence in expressions. For example, in the 
expression 2 + 9 * 4, the addition is performed first. To perform the 
multiplication first, rewrite the expression with angle brackets to show 
precedence: 2+ <9 * 4); or reorder the operands: 9 * 4 + 2. 


6.4.6 Addressing Modes 
Refer to the Motorola 68000 manual for detailed information on the 
adcressing modes supported by the 68000 microprocessor. Table 6-1 gives 
asummiary of the addressing modes including their syntax. 


Table 6-1. Summary of Addressing Modes 


Mode Register Syntax Meaning Extra Words 
6) 0..7 Di Data direct 0 
1 0..7 Ai Address direct ie} 
2 0.7 (Ai) Indirect 0 
3 OF (Ai}+ Postincrement 0 
4 O:7 -(Ai) Predecrement 0 
5 0.7 e( Ai) Indexed 1 
6 0..7 e&Ai,Ri) Offset indexed 1 
7? ie) e Absolute short address 1 
? 1 e Absolute long address 2 
7 Z e PC Relative 1 
7 3 ei) PC Relativeindexed 1 
7 4 #e Immediate lor2 


Notes: 
The indexed and PC relative indexed modes are determined by the opcode. 


The absolute address and PC relative address modes are determined by the 
type of the label (absolute or relative). 


The absolute short and long address modes are determined by the size of 
the operand. Long mode is used only for long constants. 


The number of extra words for immediste mode is determined by the 
opcode size modifier (.W or .L). 


6.4.7 Miscellaneous Syntax 
Commerts 


A comment in an assembly language program begins with asemicalon. All 
cheracters on a line after asernicolon are ignored. Examples are: 


5 This is a comment on a line by itself 
CLR.L DO ; comment after a statement 
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Current Program Location 
The current program location is indiceted in assembly language by the 
symbol “*". Examples of its use are: 


IP * ; Loop infinitely 
XP *-4 ; Jump back 4 bytes 
Move Multiple (MOVEM) 


To specify which registers are affected by Move Multiple (MOVEM), specify 
ranges of registers with "-", and specify separate registers with "/". For 
example, to push registers DO through D2, D4, and AO through A4 onto the 
top of the stack: 


MOVEM.L DO-D2/D4/A0-A4, -(A7) 


6.5 Assembler Directives 
assembler directives tell the assembler to do various functions besides 
providing directly executeble code. These functions include defining 
symbols and constants, defining macrcs, doing conditional essermbly, and 
controlling listing options. 


Tne Assembler directives (pseudo-ops} are shown in Table 6-2. 


Table 6-2 
The Assembler Directives 
Directive Operands Meaning 
PROC  <identifier> begin procedure 
FUNC = <identifier> begin function 
.DEF <identifier-list> make identifiers externally available 
-REF <identifier-list> declere external identifiers 
SEG ‘<name>’ put following code insegment ‘name’ 
-END end of entire assembly 
‘ASCII '<cheracter-string>' place ASCII string in code 
BYTE <value-list > allocate 4 byte in code for each value 
BLOCK <length>Lvalue] allocete length bytes of value 
‘WORD <value-list> allocate a word for each value 
LONG  <value-list> allocate along word for each value 
-ALIGN <Expr> allign next code on multiple of Expr 
ORG <velue> piace next byte at <value> 
-RORG <value> same as .ORG 
-EQU <vedue> set label equal to <value> 
MACRO <identifier> begin macro definition 
-ENDM end macro definition 


6-10 


workshop Liser’s Guide for the Lisa The Assembler 


Table 6-2 (continued) 
The Assembler Directives 


Directive Operands Meaning 
JAF (expr > begin conditional assembly 
ELSE optional alternate to IF block 
-ENDC end conditional assembly 
LIST turn on assembly listing 
-NOLIST turnoff assembly listing 
PAGE issue @ page feed in listing 
TITLE = ‘Xtitle>' title of each page in listing 
-MACROLIST turn on macro expansion listing 
-NOMACROLIST turn off macro expansion listing 
-PATCHLIST turn on patchlist 
-NOPATCHLIST turn off patchlist 
-INCLUDE <filename> insert <filename> into assembly 


6.5.2 Space Allocation Directives 
The space allocation directives are .ASCII, BYTE, .WORD, LONG, and 
-BLOCK. 


-ASCII 'string’ 

Converts ‘string’ into the equivalent ASCII byte constants and places the 
bytes in the code stream. The string delimiters must be matching single or 
double quotes. To insert asingle quote into the code use double quotes as 
delimiters. Similarly for double quotes: 


ASCII "don't" ; string containing single quote 
-PSCII ‘a “glitch"' ; string containing double quote 
-BYTE <values> 


Allocates a byte of space in the code stream for each of the values giver. 
Each value must be between -128 and 255. 


BLOCK <lengthoL value] 
allocates <length> bytes, each filled with the value given. If no value is 
given, a block of zeroes is allocated. 
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WORD <values> 
allocates a word of space inthe code stream for each of the values listed. 


The values must be bet ween -32768 and 65535. 
For example, 

TEMP WORD 0, 65535, -2, 17 

creates the assembled output: 


9000 
FFFF 
FFFE 
ooii 


LONG <values> 
Allocetes two words of space for each value inthe list. For ex ample, 


STUFF .LONG 0, 65535, -2, 17 
creates the output: 


00000000 
QOOOF FFF 
FFFFFFFE 
00000011 


<kabel> EQU <value> 
Assigns <value> to <Jabel>. <value> car be an expression containing other 
labels. 


ORG <value> 

Puts the next byte of code at <value) reletive to the beginning of the 
assembly file. Bytes of zero are inserted from the current location to 
<value>. 


-RORG 

is similar to ORG. It indicates that the code is relocatable. Because the 
loader does not support absolute loading, .ORG and .RORG accomplish the 
same function. All addressing must be PC relative. 


RORG (without the leading period) is the same as .RORG. Similerly, END = 
END, EQU = .EQU, PAGE =.PAGE, LIST = LIST, NOL = .NOLIST. 


6.5.3 Macro Directives 
A rnacro consists of a macro name, optional arguments, and @ macro body. 
When the assembler encounters the inacro name, it substitutes the macro 
body for the macro name inthe assembly text. Wherever Nn occurs in the 
macro body (where n is a single decimal digit), the text of the n-th 
parameter is substituted. If parameters ere omitted, a null string is used in 
the macro expansion. A macro can invoke other macros up to five levels 
deep. In the assembly listing, the listing of the expanded macro code is 
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controlled by the aptions .MACROLIST and NOMACROLIST. These 
options are described in Section 6.5.6. 


-MACRO <identifier> 


-ENOM 
defines the macro named <identifier>. The following is an example 
of & macro: 

-.MACRG Help 

MOVE %1, DO 

ADD DO, %2 

.ENOM 


If "Help" is called in an essembly with the parameters "Alpha" and "Beta", 
the listing created would be: 


Help Alpha, Beta 
# MOVE Alpha, DO 
4 0.8) DO, Beta 


6.5.4 Conditional Assembly Directives 
The conditional assembly directives IF, ELSE, and NOC are used to 
include or exclude sections of code at sssembly time based on the value of 
some expression. 


JF <expression> 

identifies the beginning of a block of source code that is assembled only 
under certain conditions.If <expression> is false, the Assembler ignores 
code until a ELSE or ENDC is found. The code between the optional ELSE 
and .ENDC is assembled if <expression> isfalse. Otherwise it is ignored. 


<expression> is considered to befalse if it evaluatesto zero. Any non-zero 
value is consideredtrue. Tne expression can also involve atest for equality 
(using <> or =). Strings and arithmetic expressions can be compered. 
Conditionals can be nested. The macros HEAD and TAIL given in section 
6.6.1 provide examples of the use of conditionals. The general form is: 


.IF <expr> 
; assembled if <expr> is true 


{ ELSE] ; optional 
. ;assembled if <expr> is false 


“ENOC 
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6.55 External Reference Directives 
Separate routines can shere date structures and subroutines by linkage 
between assembly routines using DEF and REF. These directives generate 
link information that allows seperately assembled routines to be linked 
together. 


DEF and REF directives essociate labels between assembly routines, not 
between essembly routines and Pescal.The only way to communicate date 
between Pascal and essembly routines is by using the stack. This is done by 
passing the date as parameters in the procegure or function call. 
Informstion on parameter passing between Pescal and assembly language 
is found insection 6.6. 

DEF <identifier-list> 

identifies labels defined in the current routine es available to other 
assembly routines through matching .REFs. The PROC and .FUNC 
directives also generate code similer to that generated by a .DEF with the 
same ar so assembly routines can call external .PROCs and .FUNCs 
with .REFs. 


.PROC Simple, 1 
.DEF Alpha, Bets 


BNE Beta 


Alpha MOVE 
RTS 

Beta MOVE 
RTS 
-END 


This example defines two labels, Alpha and Beta, which another assembly 
routine can access with REF. 
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-REF <identifier-list> 

identifies the labels in <identifier-list> used in the current routine as 
available from some other assembly routines which defined these 
identifiers using the .DEF directive. 


PROC Simple 


“REF Alpha 
ISR Alpha 
“END 


uses the label 'Alpha’ declared intne .DEF example. 


When a .REF is encountered, the assembler generates a short absolute 
addressing mode for the instruction (the opcode followed by a word of 0's) 
and & snort external reference with an address pointer to the word of O's 
following the opcode. If the referenced label and the reference are inthe 
same segment module, the Linker changes the addressing mode from short 
absolute to sirigle-word PC relative. If, however, the referenced procedure 
is in a different segment, the Linker converts the reference to an indexed 
addressing riode (off A5) and the word of zeros is converted into the proper 
entry offset inthe jump table. If the referenced procedure is in an intrinsic 
unit (and therefore in a different segment), the IUISR, IULEA, IUJMP, and 
IUPEA instructions are used. The Linker blindly assumes that the word 
imrnediately before the word of zeros is an opcode in which the low order 6 
bits are the effective address. Thus, a .REF label cannot be used with any 
arbitrary instruction. The .REF labels are intended for JSR, IMP, PEA, and 
LEA instructions. 


-SEG 


default segrnent name is " "(8 blanks). .SEG “segment name" puts the 
code insegment called “segment name”. 


6.5.6 Listing Control Directives 
The directives that control the Assembler's listing file output are .LIST, 
-NOLIST, PAGE, .TITLE, MACROLIST, .NOMACROLIST, .PATCHLIST, and 
-NOPATCHLIST. If you do not specify a name for the listing file inresponse 
to the assembler's prompt the listing directives are ignored. 


The default for the assembler is for LIST, MACROLIST, and .PATCHLIST 
to be in effect when the essembler starts. . TITLE defaults to blank. 


-LIST and NOLIST 

can be used to select portions of the source to be listed. The listing goes to 
the specified output file when .LIST is encountered. .NOLIST turns off the 
listing. .LIST and .NOLIST can occur any number of times during an 
assembly. 
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-PAGE 
causes the next line of the listing file to be printed on the next page. 


-TITLE ‘<title>’ 

specifies a title for the listing page. <title> can contain up to 8 
characters, and can be enclosed in either single or double quotes. For 
example: 


-TITLE ‘Interpreter’ 
places the word, Interpreter, at the head of each page of the listing. 


-PATCHLIST 
patches the forward referenced labels in the listing. It must be on if you 


want Pretty Listing. 


-NOPATCHLIST 
turns off patching of forwerd references. 


-MACROLIST 
turns on listing of the expanded code from amacro. 


-NOMACROLIST 
turns off listing of macro expansion. See Figure 6-4 for examples of the 
macro listing options. 


macro listing 


ome Se she  -- 
-ec2e@ 45E 2 pax as 

com @ o iF 46 808 

scam 8 = 4 

oe < s oF 6064 

oom 2EoF s EL (SF), (&) 

oom 475 6 RTS 

om e ay S- 4 

fp -<3] 8 oe 

Otzas e oa 

Sauna sinwmswserve ASST *.23ese7e° 

Osu 38 s 

Sm <7 ae 

oc3@ 

ose - eamsers i tet 

ase reese 

ccs 

oe 

aa -ineluss sa/eumseer 

Figure 6-4 


Macro Listing Options 
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6.5.7 File Directives 
The pseudo-op 


INCLUDE <filename> 
Causes the contents of <filename> to be assembled at the point of the 
-INCLUDE. You need not specify the .TEXT suffix. An included file cannot 
itself contain an INCLUDE statement. 

6.6 Communication with Pascal 
Assembly language routines must be called from a Pascal program. In 
order to call an assembly language routine, the Pascal program declares the 
assembly language procedure or function to be EXTERNAL. If the 
assembly routine does not return a value, use PROC. If FUNC is used, 
space for the returned value is inserted on the stack just before the function 
parameters, if any. The amount of space inserted depends onthe type of the 
function. A Longint or Real function result takes two words, a Boolean 
result takes one word with the result in the high order byte, and other types 
take one word. 


In the following example, an assembly language routine is linked to a 
Pascal program. The assembly language routine accepts two integers and 
returns the logical AND of them. The Pascal hest file is: 


PROGRAM BITTEST; 


YAR I, J: INTEGER; 
FUNCTION Iand({ i, j : INTEGER ) : INTEGER; 


EXTERNAL; (* external = Assembly language *) 
BEGIN 
i := 255; 
j := 33; 
WRITELN (1, J,’ AND =', Iand (I, J)); 
END. 
The Assembler fileis: 
. FUNC TAND 
MOYE.L (A7)+, AO ; return address 
MOVE .W (A7)+,D0 3 J 
MOVE .W  (A7)+,D1 a 
AND .W D1, D0 ; I AND J 
MOVE .W DO, (A7) ; put function result an stack 
IP (AO) 
.END 
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In the example given above little attempt has been made to rake the ~ 
assembly language procedure mimic the structure of aprocedure generated 
by the Pascal Compiler. A complete description of this structure requires 
some preliminary discourse. 


6.6.1 The Run Time Stack 

Automatic stack expansion code makes procedure entries a little 
complicated. To ensure that the stack segment is large enough before the 
procedure is entered, the compiler emits code to ‘touch’ the lowest point 
that will be needec by the procedure. If we ‘touch’ an illegal location 
(outside the current stack bounds), the MMU herdwere signals @ bus error 
that causes the 68000 to generate anardware exception arid pass control to 
an exception handler. This code, provided by the operating system, must be 
able to restore the state of the world at the time of the exception, and then 
allacate enough extra memory to the stack that the original instruction can 
be re-executed without problem. To be able to back up, the instruction that 
caused the exception must not change the registers, so a TST.W instruction 
with indirect addressing is used. 


In the normal case, the procedure's LINK instruction should be preceded by 
@ TST.W e&A7) which atternpts to reach the stack location that can 
accomodate the static and dynamic stack requirements of the procedure. If 
the stetic and dynemic stack requirements of your assembly language 
procedure are less than 256 bytes, you can assume that the compiler’s fudge 
factor will protect the assembly language procedure, so the TST.W can be 
omitted. If the requirernents are greater than 32K bytes, e(A7) may not be 
sufficient because only 16 bits of addressability are available. Inthis cese, 
the cornpiler currently emits code something like: 


MOVE.L A7, AO 
SLB .L #Size, A ;#size=dynemic + static needed 
TST .W (FO) 


If the compiler option D+ is in effect (the default), the first eight bytes of 
the deta srea following the final RTS or IMP (AO) contain the procedure 
name. The debugger gets the procedure name from this block, allowing you 
to use procedure names inthe Debugger. The following example is provided 
to show how an assembly lengquege programmer can provide the Debugger 
with all the information it needs to perform fully symbolic low level 
debugging. Note that all procedure names must be in upper case to be 
compatible with the Debugger. 
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; ASSEMBLY LANGUAGE EXAMPLE 


DEBUGF .EQU i ; true => allow debugging with 
; proc names 


HEAD — This MACRO can be used to signal the 
beginning of an assembly language procedure. HEAD 
should be used when you do not want to build a stack 
freme based on A6, but do want debugging information. 


Ne We Ne Na Ne Ne 


No arguments 


-MACRO HEAD 
oF DEBUGF 
LINK AG, #0 ; fancy NOP used by debugger 
-ENOC 
-ENOM 


TAIL — This MACRO can be used as a generalized exit 
sequence. There are two cases. First, if you build 
a stack frame, TAIL can be used to undo the stack 
frame, delete the parameters (if any) and return. 
Second, if you do not want to build a stack freme 
based on A6, this MACRO can be used to signal the 
end of an assembly language procedure. In either 
case if DEBUGF is true, the Procedure_name 

is dropped by the MACRO as an &character neme. 


Two erguments: 
1) Number of bytes of parameters to delete 
2) Procedure_Neme as string exactly 8 characters 


Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne 


-MACRO TAIL 
UNLK AG 
IF %1 = 0 
RTS ; 0 bytes of paremeters 
ELSE 
.IF “41 = 4 
MOVE.L  (A7)+,(A7) ; 4 bytes of parameters 
RTS 
ELoe 
MOVE.L  (A7)+, AO ; put return addr into AO 
ADD .4 #%1, A? ; Temove parems from stack 
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IP { AO) ; return to caller 
-ENDC 
-ENDC 
iif DEBUGF 
ASCII %2 
-ENDC 
.ENOM 


The following exemple demonstrates the use of the 
TAIL macro for the purpose of debugging. The exemple 
assumes thet you want to build a stack frame based 

on AG. In ae real assembly language procedure the 

; zeroes below would be replaced by the local size end 
perameter size. 


oe ee a 


-PROC SIMPLE 

LINK Ab, #0 ; zero bytes of locals 

NOP ; body of procedure 

TAIL 0, ‘SIMPLE ‘ ; zero bytes of parameters 

-END 
These macros ere sufficient tocall srnall assernbly language routines from 
Pescal. 


Upon entry to the assembly routine, the stack is es shown in Figure 6-5. 


pescal stack vast 


Callers Stack Frarne 


Callers Cynarmec Linv 


Static Link 
Feturn Adcress 


Gynamic Unk 


(A7) ge Low Memory 


Figure 6-5 
The Pascal Run Time Stack 
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The function result is present only if the Pascal declaration is for a 
function. It is either one or two words. If the result fits in asingle byte (a 
boolean, for exarnple), the most significant half (the lower addressed half) 
gets the result value. 


Perameters are present only if parameters are passed from Pascal. They 
are pushed on the stack in the order of declaration. All reference 
parameters are represented as 32 bit addresses. Value parameters less 
than 16 bits long always occupy a full word. All non-set value parameters 
larger than 4 bytes ere passed by reference. It is the procedure's 
responsibility to copy them. All lerae set value parameters are pushed onto 
the stack by the calling routine. 


The static link is present only if the external procedure's level of 
declaration is not global. The link is a4 byte pointer to the enclasing static 
scope. 


It is the resporsibility of the assembly language procedure to deallocate 
the return address, the static link (if any}, and the parameters (if any). The 
SP must point to the function result or to the previous top of the stack upon 
return. Registers D4 through D7 and A3 through A7 must be preserved. We 
recommend that you also preserve D3 and AZ. 


6.62 Register Conventions 
The following are the register conventions used in the Lisa system. It is 
your responsibility to preserve these registers. 


DO-D2/A0-A1: Scratch registers (car be clobbered) 


D3, A2: Scratch registers, but should be preserved 
D4-D7/A3,A4: Used for code optimization (must be preserved) 
AS: Pointer to user globals (must be preserved) 
AS: Pointer to base of stack (must be preserved) 
S$: Top of stack 


Registers D3 and A2 may be used at some time inthe future by the cornpiler 
for code optimization, so you should preserve them also. 


6.7 Assembly Language Examples 
The following examples show how to use certain features of the assembly 
language. 
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6.7.1 Using .REF and DEF Directives 
The first example illustrates the use of (REF and .DEF. These two 
directives allow an assembly language routine to reference another 
assembly routine. 


The Pascal host file is: 


progrem WasteTime; 
procedure Wait (time : integer); 
external; 
begin 
writeln (‘Going to waste some time’); 
wait (50); 
writeln (‘Finished wasting time’); 
end. 


The essembly language file is: 


.proc wait 

-ref eycle - need to use a piece of code 
whose entry point is cycle 
defined outside procedure wait 
another outside procedure 
return address in a0 

need to wait this mary cycles 
@ parameter for cycle 


ref more_time 
move.1 ({a7)+, 
move.w  (a&7)+, d0 


re ee ee 


jst cycle 
jst more_time ; waste more time 
jmp (a0) ; return 


the subroutine used by wait is defined in the 
following code. this proc could do other things 
besides the cycle routine 

.proc def_cycle 

def cycle ; cycle visible to other procs 


; code can go here 


nop ; example of a line of code 
cycle ; beginning of the cycle routine 
; parsmeter is in a0 
sub #1, dO 
pone cycle 
rts 


more code can go here 
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.proc more_time ; waste more time 


clr do ; use dO as timer 
@i add #2, dO 

bne @1 

rts 

-end 


6.7.2 String Parameters 


The Assembler 


The following program illustrates how to pess @ Pascal string to an 
assembly language program, modify the string, and return it. Pascal strings 


have their length stored as the first byte inthe string. 
The Pascal source file is: 

program pasStr; 

type strType = string[80]; 


var str : strType; 
ch : char; 


procedure AsmStr (var str : strType); 
external; 


begin 
str := ‘initial string in Pascal main progrem'; 
writeln (str); 
AsmStr (str); 
writeln (str); 
writeln; 
write (‘press any key to continue’); 
read (ch); 
end. 


The assembly language file is: 


.proc AsmStr 
move.1 (A?)+, AO ;Teturn address saved in AO 
move.1 (A7)+,Al ; address of string from Pascal 
move.l A2,-(A7) ; save scratch register AZ 
lea size, AZ 
clr.l DO 
move.b (A2),D0 ;get size of string 
move.b (A2Z)+,{Al)+  ;copy size of string 
copy subq #1, D0 ; done copying string? 
blo done ;yes, return to Pascal 
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move.b  (AZ)+, (Al)= sone cher of string 


bra copy 
done move.l (A7)+,A2 srestore scratch register 
jmp (AQ) ;return to Pascal 


size .pyte 38 ’ 
myStr .ascii ‘this string is from the LISA assembler 
-align 2 : get on @ word boundary 


6.73 Writing a Function 
The following example shows how to write afunction in assembly language. 
This function returns a boolean value. 


The Pascal program is: 
program booleanFunction; 


var int : integer; 
ch : char; 


function swapBytes (ver int : integer) : booleen; 
external; 


begin 
int := 256; 
writeln (‘the initial value of int = ', int:1); 
repeat 
if swapBytes(int) then 
writeln (‘int = ', int:1) 
else writeln (‘int = 0, function value is false'); 
int := int - 1; 
until (int < 0); 
write (‘press any key to continue’); 
read (ch); 
end. 


The Assembly language function is: 


.func svepoytes 


move.l (A7)+AO ; pop return address 
move.l1 (A7)+AL ; get address of word to swap 


move (A1), DO > get the number 


ror #8, DO ; swap the bytes 

move DO, (A1) >; put it back 

brie ai 

cir (AT) ; mumber = 0 so return false (0) 
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bra #2 
@i move #OFFFF,(A7)  ; return result true (non zero) 
@2 jmp (AO) ; return to calling program 
.end 


6.7.4 Calling Pascal I/O Routines 
The following example illustrates how to call Pascal routines from 
assembly language to do I/O. Note the use of macros for calling the Pascal 
routines. 


program APLpascal; 
type strType = string[80]; 


ver str: strType; 
fi,f2: text; 
ch: cher; 


procedure main; 
external; 


function f_rewrite (f_num: integer; f_neme: strType)-:integer; 
begin 
case f_num of 
1: rewrite (f1, f_neme); 
2: rewrite (f2, f_name); 
end; 
f_rewrite := iloresult; 
end; 


function f_reset (f_num: integer; f_name: strType): integer; 
begin 
case f_num of 
1: reset (fi, f_neme); 
2: reset (f2, f_name); 
end; 
f_reset := ioresult; 
end; 


procedure writeLine (f_num: integer; var S: strType); 
begin 
case f_num of 
O: write (s); {file id = 0 means write to -console} 
1: write (f1, $s); 
2: write (f2,s); 
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end; 
end; 


procedure writeLF (f_num: integer; var S: strType); 
begin 
case f_num of 
O: writeln (s); 
1: writeln (fi,s); 
2: writeln (f2,s); 
erid: 
end; 


procedure f_close (f_num: integer; lock_file: boolean); 
begin 
case f_num of 
1: if lock_file then 
close (f1, lock) 
else 
close(fi); 
2: if lock_file then close(f2, lock) 
else close(f2); 
end; 
end; 


begin 
writeln (‘test program - using assembly main routine to do 17’); 
writeln; 
main; 
write (‘press any key te continue’); {so user can know it is done} 
read (input, ch); 


end. 

-proc main 

ref writeLF 

.ref writeLine 

ref f_rewrite 

-Tef f_reset 

ref f_close 
first_file .equ 1 ; id # of file one 
printerlId .&qu Zz : id # of file ‘-printer' 
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; return address to the Pascal main routine is left on the stack 


-macro open_write_file 
3 %1 ——— file # 


; %2 —— file neme 

clr -(a7) ; reserve space for function 
; result from f_rewrite 

move #%1, -( a7) ; file id # as first parem 

lea %2, 80 ; second perem is file name 

move.1 a0,-(a7)} 

jst f_rewrite 

move (87)+, a0 ; pop IOresult 

ble ai 

error %2 ; IOresult > 0 -> error 

(nested macro call) 
fl .endm 


-macro open_read_file 
; 41 — file # 


: %2 —~- file name 
ely -({a7)} ; reserve space for function 
; result of f_reset 

move #%1, -( a7) 

lea %2, 80 

move.l a0,-(a7) 

jst f_reset 

move (a7)+, a ; pop IOresult 

ble gi 

error %2 ; IQresult > 0 -> error 
@i .endm 


-macro write_file > write a line (with no linefeed) 
; %1 —— file # 

3 %2 -——- label of string to be written 

move #%1, -( a7) 


les %2, al 
move.1 ai,-(a7) ; push string address onto stack 
jsr writeLine 3; write it out 

endcm 


-macro writeLn_file 
; — file # 
label of string to be written 


; write a line of text with linefeed 


41 
%2 
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move #%1, -( a7) 
lea %2, 81 
move.1 al,-(a7) ; 
jst writeLF : 
.endn 
-_macro close_file 
; %i —— file # 
: %2 —-- Close status code 
, 0 = S$OOff 
3 $0100 - Sffff 
move #%1, -(a7) 
move #%2, -( 87) 
jsr f_close 
enon 
macro  exror 
%1 —- file name 


write_file 0, errStr 


writeLn_file 0, %i 
rts 
.enan 


Se Ne SO Ne Ne 


MAIN ASSEMBLY LANGUAGE PROGRAM 


; SSSSSSsSSess SSS SSSSSSSSSSSSSSSSSSSSEBS 


open_write_file first_file, filei 
open_write_file printerId, printer 
writeLn_file 0, openstr 


writeLn_file 
writeLn_file 


first_file, string 
printerId, str1 


close_file first_file, $0100 
close_file printerId, 0 
open_read_file 1,filel 
close_file 1, $ffff 
open_read_file 2, errFile 
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push string address onto stack 
write it out 


normal close 
lock 


Ne Ne Ne Ne 


write error message 
to -console 

(file id # 0) 

output file neme also 
quit 


open I0/read.text 


write the openstr 

to -console (file # 0) 
write string to first_file 
write stri to printer 


lock first_file 
do not lock the printer 


no error should occur 
preserve filel 


no errFile around, should 
cause error. 
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rts ; back to pascal main program 
filel .byte 14 
ascii ‘IO/record.text' 
-align 2 
printer .byte 8 
ascii ‘-printer' 
-align 2 
string . byte 38 
ascii ‘this string is from the LISA assembler’ 
-align 2 ; Make sure on even memory 
stri .byte 34 
myStr -ascii ‘another string from LISA assembler’ 
-align 2 
openstr byte 26 
-88cil ‘opened file I0/record.text' 
-align 2 
errStr .oyte 22 
ascii ‘error in opening file ' 
align 
errFile byte 6 
-ascii ‘noFile’ 
-@lign 
.end 
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LISABUG 


LisaBug allows you to examine, disassemble, and change the contents 
of memory, set breakpoints, and do immediate assemblies. [i the 
compiler D opcion is on (the default), procedure names are available 
to the debugger, and Lisabug uses the symbols wherever appropriate. 


Type M to the Monitor command prompt to invoke LisaBug. It asks: 


What file? 


You can type <cr> to enter LisaBug withouc any file. If you type a 
file name, that code file is loaded into LisaBug. The LisaBug command 
prompt is ‘>’. The defaule radix is hexadecimal. 


You can drop into LisaBug by hitting the NMI key which is currently 
the third key from che left in the top row of the mimeric keypad. 


A FEW EXAMPLES 


If you type a file name, LisaBug starts up with the prograa 
counter at the start of the program. To see one instruction 
disassembled (say at 32796), type 


>ID 32F96 


(followed by RETURN, of course). ID stands for Iamediate Disassenble. 
Each subsequent ID command, if given without any address, 

disassembles the next instruction found. In addition co printing 

the value of each byte, LisaBug prints the ASCII equivalence 

of that value, if a printable one exists. If none exists, it 

prints a period. 


To disassemble 20 consecutive addresses, type 
>IL 
IL (Immediace Disassemble Lines) can also se followed by an address. 


Subsequent IL commands disassemble successive blocks of 29 
consecutive locations in memory. 


If the object file being examined was compiled with the D+ compiler 
option, the procedure names are available in LisaBug and can se used 
in any expressions. For example, 


>IL Foo 5 


, 


disassembles the firse 5 lines of procedure ‘Fao 
>BR Foots0 
secs a break poine 40 bytes into procedure ‘Foo’ 


Page 37 


The Pascal Development System Manual 16=Feb=82 


You can also use labels in immediate assemblies: 


>sy Ken 6000 
>A Ken NOP 


assemties a NOP instruction at the address ‘Ken’. 


>A 6000 <er> 
>Rich: TAS $100 
> <erd 


enters the immediate assembler at 6000, defines the label ‘Rich’, and 
assembles a TAS instruction. 


THE SYMBOL TABLE 


The symbol table is the union of the user symbol table and the distributed 
procedure names. The user symbol table contains the user declared symbols 
(like ‘KEN’ in the example above) and the predefined symbols (RDO and 
friends). Each entry contains twelve bytes. The first eight bytes are 
the symbol name, and the last four bytes are the symbol’s value. 

Location $406 gives the beginning of the symbol table, and $40A points 

to the end of the table. The section ‘Comminication with Pascal’ in 

the Assembler chapter of this manual contains more information about 

che symbol table. 
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LISABUG COMMANDS 


Definitions: 


Constant A constant in the default base 
$Constant A hex constant 

&Cons tant A decimal constant 

“ASCII String’ An ASCII string 

Name A symbol in the symbol cable 
RegNane RDO..RD7, RAQ..RA7, PC, US, or SS. 


A predefined symbol in the symbol table 

with a value set by LisaBug. The 

value is equal to the value of the 

register in question. LisaBug 

auComatically updates the values of these 
symbols. The ‘R’ is appended to distinguish 
the register names from hexadecimal numbers. 


Expr An expression. Expressions can contain 
Names, regnames, strings, and constants. 
Legal operators are +- * /. Expressions 
are evaluated left to right. * and / 
take precedence over + and -. ( and ) 
can be used to indicate indirection. 
< and > can be used to nest expressions. 
In those cases where an odd value is probably 
a mistake, LisaBug warns you that you 
are trying to use an odd address. If you 
decide to go ahead, it subtracts one from 
the address given. If the compiler option 
D+ is used, procedure names are also legal 
in expressions. 


Exprlisct A list of expressions separated by blanks. 
Register DO..D7, AO..A7, PC, SR, US, or SS. Note 


that A7 is SP (che stack pointer). 


Moving the LisaBug Window: 


P expr Sec port number to expr. Valid port numbers 
are: 
Lisa keyboard and screen (defaulz) 
l UART Port A (farthess from Power Supply) 
2 UART Port 8 


T= vou move the port to a UART, you aust have a 
modem eliminator connected to chat port. 
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Symbols and Base Conversion: 


SY name 
SY¥ name expr 


CV exprlist 


SD 


isplay the values of all symbols 

Display the value of the symbol name 

Assign expr to the symbol name 

Display the value of each expression in hex and decimal. 
Set the default radix to hex 


Set the default radix to decimal 


Assezbly and Disassensly: 


A expr statement 


A expr 


IL expr 


IL exprl expr2 


Upon enterin 


Assemble one statement (instruction) at expr. If 
you use the form A expr, LisaBug asks you for the 
statement to be assembled. You can continue 
assembling instructions into consecutive locations. 
Type <cr> to exit the immediate assembler. 
Disassemble one line at the next address 
Disassemble one line at expr 

Disassemble 20 lines at the next address 


Disassemble 20 lines starting at expr 


Disassemble expr2 lines starting at exprl 


LisaBug, the ‘next address’ is the current PC. 
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Set, Display, and Find Memory: 


SM exprl exprlise 
Set memory with exprlise sCarting at exprl. SM assumes 
that each element of exprlist is 32 bits long. To 
load different length quantities, use SB or SW described 
below. If che expression given is longer chan 32 bics, 


SM takes just the upper 32. for example, if we ask 
LisaBug to: 


SM 1000 ’ABCDE’ 


it deposits che ASCII equivalent of ‘ABCD’ starting 
ac 1000. 


SB expri exprlist 
Set memory in bytes with expriist starting at expr! 


SW exprl exprlist 
Set memory in words with exprlist starting at exprl 


SL exprl exprlise 


Set memory in long words with exprlise starting at exorl. 
For exaaple, 


SL 100 1 
{fs equivalent cto 
SM 100 0000 0001 


DM expr Display zmemory at expr. 0M Ra3+10, for axample, 
displays che concencs of memory from the addrass 
pointed to by A3 for 10 bytes. DM (110) displays 
che contents of the memory location addressed by 
the contents of location 110. 


DM exprl expr2 Display memory. if exprl < expr2, chen display 
memory from exprl to exsr2. Otherwise, display 
memory for expr2 bytes starting ac exprl. 


DB expr Display memory as bytes. 

DW expr Display memory as words. 

DL expr Display memory as long words. 

FB starting addr counc data Find Byte. 


Find the byte or bytes ‘data’ in memory > 
“starting addr’ and “starting Addr’+’coun 


FM starcing addr count daca Find Menory 


ny 


W starting addr count data 
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FL starting addr count data Find Long \ ] 


Set and Displey Registers: 
TD Display the Trace Display at the current PC 


register Display the current value of the register. 
DO, for example, is a command to LisaBug to 
display the current value in the register BO. 
RDO, on the other hand, is a name automatically 
placed in the symbol table to give you a handle 
on the contents of DO in an expression. 


register expr Sect the register to expr 


Memory Management: 


LP expr Convert logical address to physical address. 

DO expr Set the SEG1/SEG2 bits. These bits determine the 
hardware domain number. If the Status Register 
shows that you are in supervisor state, then the s 


effective domain is zero, and the domain number 
returned by LisaBug is the domain which would be 
active if the SR were changed to user state. 


WP O or l Diable (0) or Enable (1) Write Protection. The default 
is l. X 7 


MM start {end_or count] 
MM with one or two argusents displays information 
about the MMU registers. The second argument 
defaults to 1. If the starting address is 
greater than the second argument, the second 
argument is a count of the number of MMU registers 
to be displayed. If the starting address is less 
than the second argument, the second argument is 
the last register displayed. 


M™ 70 
displays 
Segment(70] Origin(000] Linie(00] Conerol[C) 


These values are the Segment Origin, Limit, and 
Control bits stored by the hardware for each MMU 
register. As can be seen from a careful perusal 

ef the hardware documentation, a Control value of 

C means the segment in question is unused (invalid). 
If che Control value is valid (F, for example), 

the debugger also displays the Physical Scart 
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and Stop addresses of the segment. 


MM &100 8 


displays che MW register information for the 8 
registers starting at register 64 (decimal 100). 


MM num org lim entrl 7 
The MM command followed by four arguments sets the 
MMU information for segment ‘num’. The Origin, 
Limit, and control bits can be changed. The 
Monitor uses the firsce 16 registers, so it is 
safer not to mess with chen. 


MM 70 100 £¢ 7 


sets the Origin of segment 70 to 100 and the 
control bits to 7 (a regular segment). The 
segment limit of -1 makes the segment 512 bytes 
long. 


Breakpoints, Patchpoints, Traces, Calls: 


BR Display the breakpoints currently set. Up to 16 
breakpoints can be handled by LisaBug. 3reak points 
are displayed both as addresses and as symbols. 

An asterisk marks the point of the breakpoint in 
the disassembly. Patch points are aarked with ‘!’. 


BR expriise Set each breakpoint in exprlist. Symbols are 
legal, of course, so we can: 


BR Ralph+4 
t£ Ralsh is a known symbol. 


PA insertion addr destination addr 
Insert a Patch. PA can be used to insert a 
sequence of code terminated by a TRAP #SE 
into another sequence of code. Lisabug saincaine 
a table of patches and return addresses to 
implement chis facility. The trace command 
works with patches. [ct displays the next 
instruccion to be executed and izs anvironmenc. 
You can have up to 16 patches. A patch can be 
removed by using the CL (Clear) command witt 
the patch insertion address. 


PA Display patch addresses 
cL Clear all breakpoines and satchpoiacts 
CL exprlise Clear each breakpoine or patchpoine in exorlis: 
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G Start running at the current PC 

G expr Starting running at expr 

T Trace one instruction at the current PC 

T expr Trace one instruction at expr 

CA expr Call a subroutine in the debugger’s environment. 
SC expr Stack Crawl. Display the user call chain. Expr 


sets the depth of the display. Ic can be omitted. 
Q Exit LisaBug, if it was called from Talk 


RM Return to the Monitor. RM checks the interrupt 
level, stops exec files, and sets the domain to 
zero. If you are in an interrupt handler, RM 
Gay refuse to do anything. If the SR shows 
2nxx where n is not zero, you are in an interrupt 
handler. To get back to the monitor, type G, 
hit NMI, and try RM again. With any luek, you 
will escape eventually. 


RB Reboot. The Lisa is reset. Reboot the Apple II 
and the Lisa should also reboot automatically. 


Overcome Inadequate Hardware: 
DU expr Disk unclamp. The Twiggy may not reliably eject 


the disk at the right time. Lf you have trouble, 


try the DU command followed by she drive number. 


Valid drive numbers are 1 and 2. 


DC expr Disk Clamp. If the Twiggy refuses to suck up the 
disk and clamp it in place, try the DC command 
followed by the drive number (1 or 2). 
RS Display the patch Return address Stack 
I= you have the debug card, 


DR ; Display index or ranges of dump RAM. 


MR Set a value level #5 interrupt on a word change. 
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register 
register expr 

A expr statement 
A expr 

BR 

BR exprlist 

CA expr 

CL ; 

CL expriist 

CV exprlise 


yscen “Manual 


Display the current value of the register. 
Sec the register to expr 


Assemble one statement (instruction) at expr. 

Display the breakpoints currently sec. 

Set each breakpoint in exprlise. 

Call a LisaBug subroutine 

Clear all breakpoints and patchpoias 

lear each breakpoint or patchpoint in exprlise 

Display the value of each expression in hex and decinal. 


DB expr Display memory as bytes. 

DC expr Disk Clamp. 

DL expr Display memory as long words. 

DM exprl expr2 Display memory. 

DO expr Set che SEG1/SEG2 bits. 

DR Display index or ranges of dump RAM. 

DU expr Disk unclamp. 

DW expr Display memory as words. 

FB starting addr count data Find Byte. 

FL starting addr count data Find Long 

FM starting addr count data Find Memory 

FW starting addr count data Find Word 

G Start running at the current PC 

G expr Starcing running at expr 

ID Disassemble one line at the next address 
ID expr Disassemble one line at expr 

IL Disassemble 20 lines ac the next address 
IL expr Disassemble 20 lines starting at expr 

IL exprl expr2 Disassemble expr2 lines starting at exprl 
LP expr Convert logical address to physical address. 


MM exprl expr2 
MM num org lia cerl 


P expr 


Display “WU information 

Set MMU information 

Set a value level #5 interrupt on a word change. 
Set port number to expr. 


PA insrtaddr destaddr Insert a Patch. 


SB exprl exprlise 
SC expr 


SL exprl exprlise 
SM exprl exprlist 
SW exprl exprlisc 


SY name 
SY name expr 


expr 


Qorl 


Display patch addresses 

Exic LisaBug, if ic was called from Talk 
Reboot. 

Return to the Monitor. 

Display the patch Return address 
See memory in bytes with exprlisc 
Stack Crawl. 

Set the defaule radix to decizal 
Set the defaule radix co hex 

Set memory in long words with exprlisce starting at exprl. 
Set memory with exprlist starting at exorl. 

Sec memory in words with exprlisc starting act expr 
Display the values of ali symbols 

Display the value of the symbol name 

Assign expr to the symbol nace 

Trace one instruction at the currence 2C 

Trace one instruction at exor 
Display the Trace Display at the currens 2C 
Diable (0) or Enable (1) Wrice Procecsi 


"1 
on 
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INTRINSIC UNIT INSTRUCTIONS 
LisaBug recognizes the Intrinsic Unit Instructions IUJSR, IUJMP, IULEA, 
and IUPEA. These instructions use the Line 1010 exception handler, and 


are created by the Linker. Full details can be found in the Development 
System Internal Documentation. 
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THE SYMBOLIC DEBUGGER 


File Needed: DEBUGGER.OBJ 
(the debugger is currently broken) 


The debugger allows the programmer to follow the execution of a 
Pascal program, set traces and break points, and display or change 
variables without the need to insert cumbersome diagnostic 
stacements. The basic unit of program execution is the Pascal 
statement and the basic unit of program data is the variable. 

If che debugger is present, run time errors drop the program into 
the debugger. 


To use the debugger, first create a .DBG file in the compiler, then 
ink the .DBG file with the output of the code generator, MPASLIB, 
and any other units that are needed. The .OBJ file thac results 

can be executed normally, or you can X(ecute DEBUGGER and hand it the 
-OBJ file. The D(ebug option in the Monitor command line also 
invokes the Debugger. 


Source Program Text 
eile 

pe 
I file DBG file 
Belg. Genoese ! 
‘snr eile 7 MPASLIB, LOADER.IMAGE, etc 
| Stag gies 
linked aw file 
which can be X(ecuted or 
passed to DEBUG 


-_—_— 


Once executed, DEBUG takes che 
firse "command: prompt occurs 
being debugged. - The available 


Set <proc [:offsec] | address> 


Sec a breakpoine at the location given. 


procedure or function. 


offset from the beginning of the procedure within 


of the procedure. You 


-OBJ file and asks you for a command. The 
juse after the starc up of the program 


commands are: 


PROC is the name of a 
The offsec, if given, specifies the byte 
the obdjecc code 
can disassemble the procedure code and 


compare it with che source to decide where cto set che dbreaksoinc. 
ADDRESS is the absolute location ac which the sreaksoint is sec. 
All numbers in the debugger are in decimal radix unless 


a? 
S$ 


prefixed with ‘S$ 


(for hexadecimal). 


The address given 
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must be in core and within the code image. 
Set Value <VarID | Address [size]> 


Set Value sets a value breakpoint at the address given, or at the 
address of the variable identifier given. VarID can be either 

an entire variable, or just a field of it. When a check point 

is encountered therafter, the debugger checks all the value breaks. 
Ié the value of the variable or address has changed, the debugger 
stops, prints the old and new values of the variable or address 

ia question, and waits for the next command. If you Set Value p* 
(which sets a value breakpoint on the variable pointed to by P)s 

do not change the value of p. You cannot set 4 value breakpoint 
on a field of a packed variable. 


Set “Varlb> 


Deposit a value in VarID. The debugger waits for the value to be 
typed. To retain the old value, type <cr>. To set the value of 
a string variable, just type the new value (without quotes). I¢ 
is not possible to set a string variable to the nuli string. String 
variables cannot be subseripted. 

Sec <Reg> <Num 


Deposit a value into one of the 18 registers (RDO-RD7, RAO-RA7, 
RPC, and RSR). 


Set “array abbreviation" mode. While in this mode, the present 
values in any array that is not a packed array of char are presented 


as first value, second value,"..", last value. 
Clear .. 

Clear .. gets you out of "array abbreviation" mode. 
Clear 

Clear clears all breakpoint and trace settings. 

You cannot clear the breakpoint which caused you to drop into the 

debugger. 
Clear <Proc [:offset]> 

Clears the breakpoint set by Set <Proc [:offsetr]>. 
Clear Value 

Clear Value clears all value breakpoints and traces. 


Clear Value <VarID | Address [Size]> 
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Clear Value removes the breakpoint specified. 
List Break 


List Break lists the currence break and trace points. 


List <Proe (:0ffsec] | Address> 


List disassembles 20 lines of code starting at the address given. 
Sometimes fewer than 20 lines are disassembled. To continue the 
disassembly from this point, type List (without any arguments). 


Regs 
Regs lists the current values of all the user registers in hexadecimal. 


Trace 


Trace puts a trace on all procedure entries, but does not display 
procedure parameters. 


Trace Proc 


Trace Proc traces all procedure and function entries, displaying 
the paramecers. 


Trace Proc <Proc (:offset] | Address> 


When an argument is given to Trace Proc, a trace is set in that 
procedure at the offset given. The parameters to the procedure 
are also displayed. 


Trace <Proc [:offsec] | Address> also puts a trace on the address given. 
The parameters to the procedure, howver, are not displayed. 


Trace Value “VarID> 


Trace value reports changes ia the value of <VarID>, but does noc 
stop execution. 


Crawl 
Crawl allows you to crawl up che stack as far as you like. Crawl 
starts ac che current PC. Ac each stack location Crawl prints che 
current value, then waits fot a carriage return. Amy response 
other than <cr> exits Crawl and returns to the command request 
of the Debugger. 

MacsBug 


The Macsbug command drops you into Lisabug (the low level debugger). 
when encered in this manner, you are still in the debugger’s 
environment. To get into Lisabug in the program’s environment, 


firsc gec che current PC of the program (from the Debugger), set a 
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Lisabug breakpoint at that location (BR or G TILL), then retura 


to the debugger. Give the debugger the GO command, and when 
the program is started back up, you are dropped into Lisabug 
in the correct environment. 


Check <Proc [soffset] | Address? 


The debugger needs to be told when to check value breakpoints and 
traces. Check sets the location at which you want these checks 
to be made. 


Ge 


Go restarts the program being debugged. 


Quit causes the debugger to return you to the Monitor. 


You can also poke around inside your code with the debugger. If you respond 
to the Command request with a name or a number, DEBUG responds as follows: 


Name’s Type Action 


Procedure or Function Display segment number and offset within 
segment of that procedure or function, 
and the routine’s in-code address, if any. 


Variable idencifier Display the current value of the variable. 
The variable can (but need not) be qualified 
by field selection, indexing, or subscripting. 
Subscripts can be either integer constants, 
or a variable of the appropriate type. 


Number Convert hex to decimal, or vice versa, 
and display 16 bytes starting at that 
memory location. If there is an equivalent 
Proc [:offset]> value, that too is reported. 


<Number> TYPEID Print memory starting at <number> as if it 
were a variable of type TYPEID. 


You should not use any identifiers in your program that conflict with DEBUG 
command names. If your program terminates norually during debugging, 
DEBUG also quits. 


lf DEBUG does not understand a command, it merely asks you again for a command. 

In general, if DEBUG does not say it has done something, then it has taken 

no action at all. 

To interrupe a program and drop into the debugger at almost any point, 
the NMI bucton on the side of the machine. In certain situations 

NMI may drop you into LisaBug instead of the’ debugger. 
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Ac link time, remember to include the .DBG extension when loading the 
debug file into the .OBJ file. The .DBG file must follow the .OBJ file 
cto which £€ corresponds in the link. All separate compilation units 
must precede the main program in the link. If you want to use the .DBG 
files, you cannot do a partial link. The .DBG files and the resulting 
debuggable .OBJ files are significancly larger than the corresponding 
-OBJ files. The Debugger cakes up about 10K of RAM plus about 60 words 
per procedure. 
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THE FILER 
File Needed: FILER.OBJ 
INTRODUCTION 


The Filer is modeled after the UCSD Pesystem’s Filer and provides a similar 


set of functions. However, there are some small but importante differences 
between the two. 


The Monitor Filer requires that a colon follow a volume name in every case. 
It provides access to as many as 20 on-line volumes. The maximum number of 
files in a volume directory is 77. 


All "workfile” commands and workfile-oriented features of the UCSD Filer 
have been omitted from the Monitor Filer. The functions of the Monitor 
utility programs Flipdir and Verify are provided by the Filer commands 
"S(ex" and "Verify," respectively. 


The UCSD Filer’s "V(olume” command has been changed to "O(n=-line" in the 
Monitor Filer. The UCSD Filer’s "eX(amine" command is not available in 
the Monitor Filer. 


The Monitor Filer’s "T(ransfer" command performs automatic verification of 
all transfers between blocked devices. 


ESCAPE aborts the currently executing function. When a wildcard R(enove 
or C(hange is aborted, you are asked whether to update the directory. 
A response of ESCAPE to this question is interpreted as ‘No’. 


The Monitor Filer includes a volume manager subsystem that permits you to 
maintain and manage the volume population on a Corvus drive. This subsysten, 
accessible through the 'M" command, replaces the old VMGR utility. 


FILER COMMANDS 


The following is a list of commands that are recognized by the Filer. 
Filer commands are invoked by pressing the key which corresponds to the 
first letter of che command name. 


B(ad=blocks - Scans for and reports bad blocks on blocked device. 


CChange - Changes a volume or file name on a blocked device. 
"Wildcard" file name specifications are recognized. 


D(ace - Sects or changes the system date. 


E(xtended 
directory 
listing - Provides a detailed list of the contents of a blocked 
volume. "Wildeard” file names specify the display of a 
directory subset. You can write a directory to 2 
printer with £ #4:,PRINTER: 
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K( crunch 


L(ise 


directory = Provides an summary of the contents of a blocked volume. 


N(ew 


O(n-line 


P(refix 


an 
% 


(uit 


R(emove 


$(ex 


= Creates the largest possible block(s) of contiguous space 
en a blocked volume by relocating existing files on that 
volume. It’s a good idea to scan a volume for bad blocks 
before any attempts are made to Krunch it. Do not Krunch 
a volume that has bad blocks. 


" above. 


See "E(xtended directory listing, 
- Creates a directory entry with the specified file name. 

Any volume name used to prefix the file name must be 

that of an on-line, blocked device. You can attach 

a size-specification suffix to the end of the file name. 

This suffix indicates the number of blocks to be occupied 

by the new file. The suffix consists of a non-negative 

integer constant or an asterisk ("*"), enclosed 

in square brackets ("{]"). For example, 


FARLEY :MYFILE.TEXT[40] 
XRAY. OBJ [*] 


The new file is placed on the specified volume in the 
first empty space that is large enough to hold it. 

The asterisk indicates that the file should fill half the 
largest free area on the volume, or all of the second= 


largest area, whichever is larger. In the absence of a size 
specification, the newly-created file oecupies the largest 


area of contiguous free blocks on the volume. Files 


created with N(ew are stamped with the current system date, 


while the storage areas to which they correspond are left 


unaltered. N(ew permits the creation of zero-length files. 


- Provides a list of all velumes that are on-line. 
= Changes the system prefix volume name. 
- Exits the Filer. 


- Deletes entries from the directory of a blocked volume 
on a single~file or "wildeard" basis. 


- Performs sexual reassignment of a blocked volume’s 
directory. This command corresponds to the FLIPDIR 
utility. The Lisa is a female machine, whereas the 
Apple II is a male machine. 


~ Copies and transfers information between volumes. 
Single-file or miltiple-file wildcard transfers are 
allowed. You can also transfer between blocked 
and unblocked volumes. Transfers between blocked volumes 
are automatically verified, but transfers involving 
unblocked volumes are not. 


Page 54 


16=Feb=82 


wy 


The Pascal Developmene System Manual 16=Feb=82 


V(erify - 


Z(ero 


vM(gr 


L(ise 


Compares blocked files for equality. You can compare 
Single-files or mitiple files common to two blocked volumes. 
Wildcard specifications can be used to name the comparands, 
so subsets of the files on one volume can be compared with 

a@ congruent subset of files on another volume. Verify 
detects and reports the following situations: 


* The “source” and “destination” files match; 

* The source differs from the destination in 
date-stamp, size, and/or contents (contents 
are always compared if sizes match, whether 
or not dates match); 

* No counterpart to a given source file exists 
on the destination volume. 


The report produced by Verify can be redirected to a 
device or file other than the console by following 
the destination file/volume name specification with 
a comma, then the name of the desired output device 
or file. For example, 


Verify what file/vol 7? VOL1:,VOL2:,PRINTER: 
is equivalent to: 


Verify what file/vol 7? VOLI: 
Against what file/vol ? VOL2:,PRINTER: 


The verification report in either of these cases is 
diverted to the PRINTER: device. 


Erases and initializes the directory area of a blocked 
volume. If the volume already has a directory prior to 

the Z(ero, you have the option of retaining the old 

volume name and/or volume size. 2Z(ero can be used to 
inerease or decrease the size of the virtual volume MEMORY:. 
Caution should be exercised, however, because ic is possible 
to specify a volume size that is auch larger than the LISA 
memory complement permits. In this case, a "memory overflow" 
is reported, and you should again invoke Z(ero to shrink 
MEMORY: to a reasonable size. Do not leave che Filer 

or attempt to use MEMORY: after receiving the "memory 
overflow" message! 


Remember thac Z(ero produces an empty directory. Therefore, 
to change the size of MEMORY: without erasing the directory, 
you aust still use che CHANGEMEM ucility. 


- Enters the volume manager (vMgr) subsystem, which presencs 


its own sub-menu, and offers the following commands: 
List che hard disk Volumes (like Filer’s O(n-line command). 


From time to time, you may destroy the directory of one or 
more volumes that reside on che hard disk. The vMgr 
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M(ount 


New 


Q(uit 


R(emove 


U(nmoune 


W(rite= 
protect 
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subsystem assigns temporary names to these "bad" volumes 
so that you can be warned of their contamination, and can 
also manipulate them, if necessary. The form of such 
temporary names is BAD*n, where n is an integer (e@cge, 
BAD*1, BAD*10, etc). Temporary names for “bad" volumes 
are effective only within the vMgr subsystem. 


M(ount assigns a hard disk volume to a specific Monitor device 
number, taken from the set (4,5, 9..20]. You can specify 

the device number to which a volume is associated, or you 

can accept the defaulz selected by the vMgr. When vMgr 

picks a default unit number, it chooses the highest number 
that is not currently in use. 


N(ew creates new volumes. You can accept the default 
values for volume size and location as offered by the 
vMgr, or specify your own. 


Leave vMgr subsystem. If you have made any changes to the 
volume table you must confirm whether or not they should be 
made permanent in the default mount table. If you respond 
with any character other than “Y’, any changes made are ° 


temporary ~~ when the system is rebooted, the original 
settings will take effect. 


R(emove unmounts and destroys a volume. You can R(emove a 
M(ounted volume, but to do so you must approve the 
U)nmounting of that volume. 


U(nmount is comparable to removing a floppy from a drive. It 


disassociates the volume from the unit on which it was mounted. 


The U(nmounted volume and the data it contains still exist 
on the hard disk drive, but can not be accessed through any 
Monitor device. 


W(rite=protect toggles the write-procection status for a 
volume. The contents of a write=protected volume cannot 
be changed. This command changes the default mount table. 
Newly-created volumes are not write-protected. 


See the Apple Pascal Operating System Reference Manual for further information. 
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PROFILE OR CORVUS INSTALLATION 


To comnect a Corvus or Profile hard disk to your Lisa: 


l. 


Turn everything off. You need two floppy disk drives, a controller 
card, and the latest monitor release with both the male and female 
boot volumes. 


Set up the Apple so that drives #4 and #5 are available. Do not 
connect the hard disk yet. 


Place the male boot volume in #4: and the female booet volume in #5:. 
Turn on the Apple, the Lisa, and the hard disk. After awhile, the 
Monitor command line should appear on the Lisa. 


Plug the hard disk cable into the parallel port on the back of the 
Lisa. If the monitor command line starts flickering, type RETURN. 


Execute NEWZERO and respond “Y’. NEWZERO initializes the hard disk 
mount and volume tables. 


Execute the Filer and enter the volume Manager (type M). 


‘Create (N(ew) a volume (MBOOT:) with 2048 blocks of space. Mounce ict 


as #20: (or anything other than #5:). Q(uit the Volume Manager and 
update the mount table (type “Y’). 


Transfer all of the files on the female boot diskette (#5:) to the new 
volume (#20:). T #5:2,#20:5 


Enter the Volume Manager again and moune the new volume as #5:. 
QCuit the volume manager and update the mount table. 


Turn everything off. See up the floppy disk drives as #9: and #4: 
(i1f you have two disk controller cards). Place the male booc volume 
in #4:. Turn on the Apple, the Lisa, and the hard disk. 


Copy the entire monitor release onto the famale boot volume (#5:), but 
do not overwrite any files that are already on #5:. 
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THE EDITOR 


File needed: EDITOR.OBJ 
LISA: EDITOR. FONT 
LISA: EDITOR. MENUS 
LISA: SYSTEM .FONT 


INTRODUCTION 


The mouse oriented editor is invoked by the monitor command E. Unlike the 
UCSD editor (invoked by U), this editor adheres to the Lisa User Interface. 
When invoked, it displays its menu, a portion of the Scrap folder, and 

a dialog box which asks you for the name of the file to be edited: 


Get Document named? 


Type the name of the desired file, followed by <RETURN>. The editor opens a 
folder and displays the first portion of the file. To open an empcy folder 
(to start a new file), type juste <RETURN> to the request for a document name. 


The arrow or I=beam shows the current position of the mouse. The blinking 
vertical bar marks the insertion point. Activity takes place at the 

insertion point even if thac point is not visible. If, for example, 

you open a folder, scroll to the end of the file, then start typing, the 
characters you type are inserted at the start of the file (where the cursor is), 
rather than ac the end of the file (which you are merely looking at). 


To mark text to be deleted or copied, set the insertion point to the start of 
the text (move the mouse there and click), then drag the mouse through the text 
to be acted upon. Selected text is displayed in inverse video. Click twice 

to select a word, three cimes to select an entire line. To select large 

pieces of text, put the cursor at the start of the text, move the mouse 

to che end of the text, and shift click ac that point. 


at any time you can, 


Open a new folder 
(selece the PULL item in the DESKTOP menu) 


Start editing in any folder on the screen 


(select the desired folder from the tray icon menu, or 
elick in the body of the desired folder) 


Move the folder around on the screen 
(drag the folder’s tab) 


Make the folder larger or smaller 
(drag the grow box. The grow box is the square in the 
lower righce corner of the folder) 


Scroll up a line 
(click the up arrow box in the lower right corner. To 
scroll continuously, hold the button down in the box) 
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Seroll down a line 
(elick the down arrow box in the upper right corner. To 
seroll conginuously, hold the button down in the box) 


Jump back a windowful 
(elick in the grey area above the elevater. Hold the 
button down in this area to continue flipping pages. 
The elevator is the empty box in the vertical seroll 
bar) 


Jump forward a windowful 
(elick in the grey area below the elevator. Hold the 
button down to continue flipping pages) 


Jump to certain place in the folder 
(drag the elevator to the position in the scroll bar that 
corresponds roughly to the desired position in the file) 


Cut out the selected text and place it in the Scrap 
(selece the CUT item in the EDIT menu, or type Command=Z) 


Paste the Scrap contents into the folder at the selection point 
(select PASTE in the EDIT menu, or type Command=-X) 


Copy the selected text into the Scrap 
(select COPY in the EDIT menu, or type Command=-C) 


Adjust che selected text right one space 
(select ADJUST RIGHT in the EDIT Menu, or type Command=R ) 


Adjust the selected text left one space 
(select ADJUST LEFT in the EDIT Menu, or type Command-L) 


Save all your edits and close the folder 
(select PUT BACK in the DESKTOP menu) 


Save all your edits, but remain in the folder 
(select ACCEPT ALL EDITS in the DESKTOP menu) 


Write the current folder contents to another file 

(select CROSSFILE TO... in the EDIT Menu. CrossFile asks 
you for the file name to cross file to. If that file 
already exists, you are given a chance to change your 
mind before the old file is overwritten. CrossFile does 
not change the file name used by Accept All Edits or 

Put Back. If you do not want to crossfile after all, 
type <RETURN> as the filename). 


Cancel all the editing done since the last save command 
(Select UNDO ALL EDITS from the DESKTOP menu. The editor 
gives you a chance to change your mind before it cancels 
all your edits). 
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Exit from the Editor 


Sec tab 


(Selece EXIT EDITOR from the DESKIOP menu. I there are 
unsaved edits in the folder, the editor asks you if these 
should be thrown away. The prompts force you to answer 
"Y" then "N" or vice versa to be able co get out, which is 


less than friendly.) 


stops 
(select SET TABS... from the EDIT Menu. You can change the 
number of spaces between tab stops. The default is eighc) 


Find some target string starting from the current selection 


(select FIND... from the SEARCH Menu. The default search 
ignores case and is token oriented. To change either of 
these, select the appropriate item in the SEARCH menu. FIND 
asks you for the target string. To find the same thing again, 
select FIND SAME. FIND & PASTE ALL performs a global find 
and replace. FIND can be invoked by Command-F, and FIND 

SAME can be invoked by Command-S. Only the firse eight 
chatacters of a token-oriented search target are significant). 


To move text from one folder to another, select and COPY the text from the 
source folder, activate the destination folder, set the cursor to the desired 
insertion point, and select PASTE. 


CUSTOMIZING THE 


The editor uses 


EDITOR 


whatever fone it finds in the file LISA:EDITOR.FONT to 


display the folder contents. The suggested fonts are: 


TITLEL2R12S.F 20 lines x 82 chars 

SARA8.F 26 lines x 83 chars 

TILEX.F 32 lines x 82 chars (default) 
TILE7RI5S.F 32 lines x 94 chars 
TILESR18S.F 37 lines x 132 chars 
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THE UCSD EDITOR 
File needed: UCSDEDITOR. OBJ 
INTRODUCTION 


The Editor is divided into the modes listed in the Editor’s 

command line. A mode is invoked by typing the first letter of its 

mame. Many of these modes also have command lines to further specify 
what accion the Editor is to take. To insert new text, for example, 

you must type I when at the tep level. Once in Insert mode, text can 

be inserted ac that point in the file simply by typing it in. - To 

accept the insertion type Crerl-C (ENTER). To forget the insertion, type 
<ESCAPE> (the CLEAR key in the numeric keypad). To get to another mode 
(to move to a different place in the file, for example), you must first 
exit che mode you are in. 


The entire file being edited aust be in memory at all times during 

editing. There is no macro facility. The cursor is sometimes not where it 
appears to be. If a key {ts held down for more than a fraction of a second, 
the key’s action is repeated at about 10 times per second. 


Elaborate documentation can be found in the Apple /// Introduction, Filer, 
and Editor Manual or in the Apple ]({ Pascal Operating System Reference 
Manual. The Apple ]{ manual is somewhat inaccurate because our Editor 
its an enhanced version of the Pascal 1.1 update of the original Editor. 


CURSOR MOVEMENT 


Numerical Arguments 
Most commands can be preceded by a numerical 
argument. The argument can be an integer 
between O and 9999, or the character / 
which means "as many times as possible". 
The numerical argument defaults to l. 
Ie is abbreviated as "n" below. 

See Direccion 
The Set direction is the direction in 
which some commands move through the file. 
The first character in the command Line 
tells whae che currence direction is: 
> is forward, < is backward. 


Ac the top level of the Editor, the keys 


> . + 
change the direction to forward, and 
Sc iy = 


change it to backward. 
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Simple Cursor movement 


<SPACE> move n spaces in set-direction 
<RETURN> move n lines in set-direction 

(you end up at the start of the line) 
Uparrow move n lines up 


Down=Arrow move n lines down 

Leftw-Arrow move n spaces left 

RightwArrow move n spaces right 

<TAB> move n tab pesitions in set-direction 

<=>. move to start of last text replaced, found, 
or inserted 

0 move to start of line 

$ move to end of line 

Ww move to beginning of next word 

E move to end of current word 

B move backward one word 

By move to the next occurrence of a specified 
character 


You can also use the main keyboard "h", "Jj", "k", and "1" 
Keys for cursor movement: 


h move left 

j move down 

kK move up 

1 move right 


GCete 
Jump to some place in the file. You are presented 
with a secondary command line to tell the cursor 
where to Jump: 


B(eginning of file 
E(nd of File 


M(arker 
Jump to a specific marker. You can have up to 10 active 
markers set by the Set command (see below). Markers are 
pointers to file, not text, locations. You can return to 
the point you jumped from if you immediately type 
<ESCAPE>. 

PCoint 


like <=> above. 
<ESCAPE> exits without Jumping. 


P(age 
Move the cursor n windows in the set-direction. 


F(ind 
Find a target string and place the cursor just after it. 
The normal mode is case sensitive. With the exceptions 
of S, L, U, and T, the first character following 
the F (for FIND) is the delimiting character. The 
target string specification ends when che delimiting 
character is repeated. Thus F.hi. looks for one 
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occurrence of the lowercase word "hi". /F(HI( places 


the cursor after the last occurrence of the uppercase 
word "EI", 


L(iteral, T(oken 
FIND can be told to look for any occurrence of the 
target string (Literal mode), or only for delimizced 
occurrences (Token mode). The default is the one 
not given as an option when you type F (usually 
Token mode is the default). To override the default 
for one search, type L or T after F, but before the 
delimiting character. FL.hi. looks for any occurrence 
of the two characters "hi" in the file. A delimiter 
(for Token mode) is any character which is noe a 
letter or a number. See S(ee E(nvironment below 
to change the default mode. Note also that 
FL/<RETURN><RETURN>/ finds the next blank line. 


U( pper-and=-Lower-Case 
To get a case insensitive search, type U before che 
delimiting character. FU.hi. looks for any occurrence 
of “EI”, "HL", "SL". of “hl” ia Che file. 


S(ame-String 
To repeat a search using the same target string as 
was used in the last search, you can type S in place 
of the delimited string. The Eavironment information 
(see S(ec E(nvironment) tells you the currence target 
string. If we last searched F.hi., FS searches 
again for "hi". Mode changing letters can be 
concatenated: FLUS looks for the target string last 
specified, in Literal mode without sensitivity to 
upper or lower case. 


<ESCAPE> 
exit Find mode without taking any accion. 


TEXTUAL COMMANDS 


I(nsert 
Insert text into a file. Insertion takes place 
becween the character on which the cursor is sitting 
and the character immediately to its left. trl-Cc 
accepts an insertion, <ESCAPE> forgets it. At any 
point during an insertion, left arrow deletes the 
character to the left of the cursor. You can’t 
backspace past che beginning of the insertion. 
If you accidentally hit <ESCAPE> during an insertion 
(and thereby delete everything you just typed), 
you can rescue the inserted texe by Clopying ic 
from che B(uffer. 


The Pasca 


D(el 


Z(ap 
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ete : 
Delete text moving in the Set-direction. Ctrl-C accepts 
a deletion, <ESCAPE> restores the deleted text. All deleted 


texe is stored in the Copy Buffer, so to move a piece of text 


from one place to another, first delete it, sove the 
cursor to the new location, then C(opy from the B(uffer. 
D(ielete accepts numerical arguments (including / 

and P(age). 


Delete all text between the current cursor position and 
the current location of the "Poine”™ (the location of the 
last text inserted, found, or replaced). Zapped text 

is placed in the Copy Buffer. 


C(opy 


Copy text into the file at the current cursor position. 
The copied text can be taken from the Copy Buffer, or 
from a file. 


Copy a file, or some portion of that file. If the file 
has markers placed in it, you can choose to copy only 
the portion between any two markers by enclosing the 
names of the markers in square brackets after the file 
name. HI.TEXT({PROC1,PROC3] copies the portion of HI.TEXT 
lying between the markers PROC] and PROC3. [ ,MARKER] 
copies from the beginning of the file. to MARKER, and 
[MARKER, ] copies from MARKER to the end of the file. 
If no marker specification is given, the entire file 
is copied. 

B(uffer 
Copy the contents of the Copy Buffer. 

M(arker 
Copy text between two markers, using exactly the same 
syntax as that used in copying from a file. 

<ESCAPED 
Exit Copy mode without copying anything. 


X( Change 
Exchange mode allows you to overwrite text (exchange 
old text for new). You cannot exchange characters 
past a <RETURN>. Ctrl-C accepts an exchange, <ESCAPE> 
forgets it. Right arrow copies characters as it passes 
over theme 

R(eplace 


R(eplace mode is very similar in syntax to the F(ind 
mode. R(eplace takes two strings--the target string 
(as in F(ind), and the string to substitute for an 
occurrence of the target. Numerical arguments are 
valid. - 

L(iteral, T(oken 
See F(ind above. 

U(Cpper-and~Lower-Case 
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See F(ind above. 

S(ame=String 
See F(ind above. Note that S can be used for either 
of both strings: RSS looks for the previous target 
string and replaces it with the previous substitute 
string. 

V(erify~ 
If the find-and-replace operation is done in V(erify 
mode, you are asked before each replacement whether 
the replacement should take place for the given 
occurrence of the target. /RV.hi./ho/ looks in the 
set-direction for every occurrence of "hi", then on 
each one asks you if you really want to replace thac 
"hi" with "ho". 

<ESCAPE> 
Exit Replace mode without replacing anything. 


A(djust 
Adjust the indencation of a line, or a group of lines. 
Left and Right Arrow push the entire line left or right. 
<SPACE> moves a line a space in the set direction. 
Up and Down Arrow cause the same adjustment to affect 
lines above or below the first adjusted line. <RETURN> 
affects the lines above or below, depending on the 
set direction. <TAB> moves lines over 8 spaces. 


Alternate choices are: 
L(eft-justify 
R(ight-justify 
C(enter 
P(age 


Ctrl-C accepts the adjustment--you have no other choice. 
Numerical arguments (including /) can be used. 


M(argin 
The M(argin command attempts to fic a paragraph into the 
prevailing paragraph formatting parameters set in the 
E(nvironmenct. M(argin only works when I(ndent-Auto 
is false and F(illing is true. A paragraph is defined 
to be any text bounded above and below by two delimiters. 
The allowed delimiters are a blank line, the beginning 

. of che file, che end of che file, and a line which 

begins with the Command Character. To M(argia a 
paragraph, move che cursor to any poine within the 
paragraph and ctype M. 

O(bscure 
O means "join" for some reason. [ec replaces the <er> ac 
the end of che current line with a space, thereby joinin 
the two lines. 
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EDITOR DIRECTIVES 


S(et 

S(et mode allows you to set Markers and to change 
various glotal Editor settings-~ 

M(arker 
A Marker is an absolute location in a file to which 
you can J(ump. A maxicua of ten markers can be active 
at one time in a file. To set a marker, move-the 
cursor to the desired location, then type SM. You 
are then asked for the marker’s name (a character 
string of up to 8 characters). 

E(nvironment 


The editing "environment" can be customized to suit 
your whims. The E(nvironment command displays the 
current settings of various parameters, the current 
size of the file, the current target and replacement 
strings for F(ind and R(eplace, the markers currently 
in the file, and various other information. 


To change the setting of the parameters, type the first 
letter, then the new value. SEAF, for example, enters 
S(et mode, enters the E(nvironment menu, then sets 
A(uto~Indent to False. To exit the Environment menu 
and retain the changed values, type Ctrl-C (ENTER) « 


A(seii-file 
Used by BASIC on Apple ///. Not applicable to Lisa. 


C(ommand Character 
You can set the Editor Command Character to be any 
printing character. The command character can be 
used to protect a line from the Margin command. 


F(illing 
If Filling is true, lines are automatically broken at 
the right margin between words. 


I(ndent-Auto 
If I(ndent-Auto is true, a new line is automatically 
indented to the position of the first non~space character 
of the previous line. 


Left, R(ight, P(aragraph margin 
These three parameters control the layout of the 
paragraphs when using Filling or Margin. P(aragraph 
margin is the indentation of the first line of the 
paragraph. 


N(amewof-file 


When you Q(uit the Editor, the S(ave option can be 
used to write the edited file to the ‘file named in 
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the N(ame field. You can change this name to any 
legal file name. 


S(pace-continue 
If TRUE, a space must be typed before you can continue 
editing after an error has occurred. If FALSE, any 
character can be typed to allow you to continue. 


Tloken 
Token defines whether the F(ind and R(eplace commands 
use the T(oken or L(iteral mode as a default. 


<ESCAPE> 
Restore all the parameter values that were in force when 
Set mode was entered, and exit Set mode. 


Verify 
V(erify causes che Editor to redisplay the screen. 


Q(uit 
Exit the Editor or load a new file. 
U(pdate 
Update the "workfile". Ir is not an accident that 
this is che only mention of the “workfile". 
E(xit 
Exit the Editor without saving anything that you did. 
R(eturn 
Return to the Editor (in case you didn’t wane to quit). 


S(ave 
Save the current edited file under the name given 
when the Editor was entered, or (if you started a new 
file) under the name last given in a W(rite command. 
Return to Q(uit menu. 

W( rite 


Wrice che current edited file co a diskette file. 
You aust give the file’s name. W(rite returns to 
QCuit menu. 

C(hange 
Load a new file into the Edicor without vrestarting the 
Editor. The previous target and substitution strings are 
carried over, and the copy buffer is maintained intace 
(if possible). 
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(IUManager, ChangeSeg, SegMap) ... 2... ee ee ee eae 


(Configure, Contrast, SecS?, ChangeMem, Flip4, 


(FileDiv, FileJoin) 


UTILITY PROGRAMS 


(DL££, FindID, Pretty List, PascalRef).. 


(DumpObj, DumpHex, Patch, ObjDiff, ByteDifé 


(LisaTest) ....- 


(Perform, Coverage Analysis) .....s.es 


CSCELDE) sm 2 hw, 6 Sem @ ele Orwue Ue 


(Terminal Emulator). 
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TUMANAGER 


IUMANAGER modifies the file INTRINSIC.LIB used by the intrinsic unit 

Linker and loader to find the intrinsic unit files. INTRINSIC.LIB 

is essentially a directory of unit names, segment names, and file names. 
When executed, IUMANAGER asks for the input and output files to be modified. 
The default name for both files is *INTRINSIC.LIB. The intrinsic unic 
manager has three modes: Manage Segments, Manage Units, and Manage 

Files. Each mode operates on an associated table of information used 

by the loader to properly link intrinsic unit code and data into an 
executing program. 


Manage Segments Mode operates on the Segment Table which contains a list 
of segment names with information about each segment for the loader and 
linker. Manage Units operates on the Unit table which contains the 

unit names and information used by the loader and linker to build the 
data pointer table. inally, Manage Files operates on the File Table 
which contains a list of files indexed by a file number. The loader 
uses che file number to find the intrinsic units and segments on the 
disk. 


TUMANAGER has the following commands: 
Q(uit Write the output file and exit from IUMANAGER. 


S(egmencs Enter the Segment Manager and list the contents of 
the Segment Table. 


U(nits Enter the Unic Manager and list the contents of the 
Unit Table. 


F(iles Enter the File Manager and list the contents of the 
File Table. 


In each of the modes you can: 


L(ist List the contents of the currently active table. 
Tf you have more than 32 entries in the table, 
you can stop the listing with Control-S {the 


Cs 


‘sw’ key on the numeric keyboard). 

R(emove _ Remove an entry from the currently active cable. 

C (Change Modify information in the currently active table. 
The Change command prompts you for the value of 
each field. A response of <cer> accepts the default. 

N(ew Create an entry in the currently active table. 


The New command prompts you the value of each field. 
A response of <cr> accepts the default value. 
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In the File Manager you have one further command choice: 
I(nastall Install (update) the segmene and unit tables from 


a linked object file. The Install command prompts 
you for the file number of the entry to be updated. 
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CHANGESEG 


CHANGESEG changes the segment name in the modules in an object file. 
The first prompt asks for the object file you want to change: 


File to change: 


Changes are made in place (the file itself is changed). You are nexe 
asked: 


Map all Names (Y/N) 


If you want to change segment names in all modules, respond Y. If you 
want to be prompted for the new segment name for each module, type N. 
A response of <cer> accepts the default name. 


SEGMAP 


SEGMAP produces a segment map of one or more object files. The first 
prompt: 


Files to Map ? 


accepts either an object file name or a command file name. A command file 
must be preceded with a <. SEGMAP adds the .TEXT suffix to the command 
file name. The next prompt: 


Listing File ? 


directs the map information to the file given. A response of #1: or 
CONSOLE:, for example, send the map information to the screen. The 
map information includes the object file name, the name of the unit 
in the file, the names of the segments used in that unic (if any), 
and the new segment names. 
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CONFIGURE 


CONFIGURE modifies some of the vectors in the Monitor Map Table. 
These vectors are stored in CONFIG.DATA on the male boot volume 
and are used by the Monitor to configure your system when it is 
booted. To use CONFIGURE, copy CONFIG.DATA from che male side to 
a female volume, or flip the sex of the boot diskette.  <X(ecute 
CONFIGURE. CONFIGURE asks you whether it should Go or Quit. Type 
G cto run CONFIGURE, Q to return to the Monitor command Line. 
CONFIGURE asks you for the file containing the vectors you want to 
change. If you do not give a volume name, it look on the prefix 
volume. If you give just the volume name, it looks for CONFIG.DATA 
on that volume. CONFIGURE can change the following vectors: 


dE(bug pointer ($150] 
D(efaule Stack pointer {$13c] (* most important *) 
H(eap pointer ($138] 
C(orvus pointer ($134] 
U(art pointer [sive] 
A(pple port [$118] 
M(emory top ($114] 
S(creen base ($110] 
Buffer pointer ($1l0C] 


The old and new value of each vecrors is also displayed. Type the 
capitalized letter of the vector you want to change. Lower case is 
allowed in hexadecimal numbers. When you are done, type Q to Quir. 

Ac this point you are asked where to save the new values. You can 
write the changes back to CONFIG.DATA, exit without making any changes, 
and so on. 


A memory aap is given in the Monitor chapter showing the relationship of 
these vectors. Do not place the start of the heap above the stack pointer. 
Because CHANGEMEM sets aside heap space, it is safer to set the stack 
pointer before grabbing a lot of the heap with CHANGEMEM. 


Once you have finished modifying CONFIG.DATA, transfer it back to the 
male Scoot volume so chat it can take effect when the syscem is rebooted. 


CONTRAST 


CONTRAST changes the contrast setting of your screen without changing the 
default setting. It is a simple program that should be self-explanatory. 
Like CONFIGURE, ic first asks whether to G(o or Q(uic. If you type G, 

some alphanumeric characters are scattered around the screen for reference. 


You can type >’ or *.’ to increase and ‘’<’ or ’,’ to decrease the screen 
contrast. 
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SETSP 


SETSP sets the address at which the stack pointer starts. Memory above 
that address is then reserved for code, and memory below it is the stack 
ang heap space. If your program requires a great deal of room 

for data, set the stack pointer to & high address. If the program 
requires a great deal of code, set the SP to a low address. The 
Monicor default SP starting address depends on the version of 
CONFIG.DATA on your male boot volume. The highest possible address 

is the bottom of the Monitor. 


All SETSP I/O is in hex. When X(ecuted, it displays the current 
stack pointer value. Type 0 to exit the program. The optimal value 
to give SETSP may not be obvious at first, since code swapping can 
change your memory requirements. Ie is quite possible that 4 program 
will run happily for hours, then die with a Loader Error when a 

piece of code couldn’t be fit in memory. If this happens, set the 
stack pointer to a lower starting address, and try again. 


CHANGEMEM 


CHANGEMEM changes the size of the predeclared RAM~resident volume MEMORY: . 
Its interface is identical to that of SETSP. The default size of MEMORY: 
is 10 blocks. Space for the MEMORY: volume is taken from the available 
heap space. 


FLIPG 


Volume #4: is normally the RAM=based volume MEMORY:. The Disk drive 

that would usually be #4: is hidden from the monitor to avoid overwriting 
the male boot volume. If you want access to that disk drive from che 
monitor, run FLIP4. LIP4 executes a simple loop until you tell it to 
Quit. After asking whether to continue or to quit, FLIP4 gives you a 
chance to toggle the state of #4:. #4: is either MEMORY: or the disk 
drive. Remember to remove the male boot volume before writing to #4:. 


MOVESOROC 


MOVESOROC (also sometimes known as MS) determines where the Pascal WRITELN 
output goes. It normally is sent to the Lisa screen. When an application 
is running on this screen, however, debugging WRITELNs mess up the program’s 
pretty outpuc. MOVESOROC redirects this output to either the Apple monitor, 
the UART (serial port #2), or back to the Lisa. Monitor input always comes 
from the terminal to which output has been directed. 
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FILEDIV and FILEJOIN 


Ie is often necessary to distribute files that are too large to fit onto a 
single floppy diskette. FILEDIV can be used to break a large file 

into several diskette-sized pieces. FILEDIV can then be used to rajoin 
these pieces at the file’s destinacion. These two programs replace the 
TRANSFER program. 


To divide a large text or object file, execute FILEDIV. 


Input file: <give the name of the file to be divided> 
Output file: <give the name to be used for the output files> 


Do not include the suffix in the file name. Lf, for example, you want 

to divide TEMP.TEXT, give TEMP as the input file, and TEMP (or whatever) 

as the output file. FILEDIV will create a group of files named TEMP.1.TEXT, 
TEMP.2.TEXT, and so on, until TEMP.TEXT is completely divided up. If you 
use the drive number (#9:, for example), rather than the volume name, the 
new files can be written to multiple diskettes. When space on a diskette 
is exhausted, FILEDIV asks you to insert another diskette. 


To rejoin the pieces of the file, execute FILEJOIN. Using the example given 
above, we can rejoin TEMP.1.TEXT and friends into TEMP.TEXT by responding: 


Input file: TOP “will read TEMP.1.TEXT, etc> 
Outpuc file: TE <will create TEMP.TEXT>D 


FILEDIV and FILEJOIN use regular directories, so a spurious sex change 
Cannot destroy your file. Files are verified in both directions. 


~! 


~~ 
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DIFF 


DIFF is a program for comparing ".TEXT" files, in the LISA Pascal 
development environment. DIFF is strongly oriented toward use with 
Pascal or Assembler source fee. 


DIFF is not sensitive to upper/lower case differences. All 

input is shifted te a uniform case before comparison is done. 
This is in conformance with the language processors, which ignore 
case differences. 


DIFF is not sensitive to blanks. All blanks are skipped during 
comparison. This is a potential source of undetected changes, 

since some blanks are significant (in string constants, for instance). 
However, DIFF is insensitive to "trivial" changes, such as indentation 
adjustments, or insertion and deletion of spaces around operators. 


DIFF does not accept a matching context which is "too small". 
The current threshold for accepting a match is 3 consecutive matches. 
The M option allows you to change this number. This has two effects: 


Areas of the source where almost “every other line” has been 
changed will be reported as a single change block, rather than 
being broken into several small change blocks. 


Areas of the source which are "entirely different" are not 
broken into different change blocks because of trivial similarities 
(such as blank lines, lines with only "begin" or "end", etc.) 


DIFF makes a second pass through the input files, to report the 

changes detected, and to verify that matching hash codes actually 
represent matching lines. Any spurious match found during 

verification is reported as a "JACKPOT". The probability of a JACKPOT 
is very low, since two difference lines must hash to the same code at a 
location in each file which extends the longest common subsequence, and 
in a matching context which is large enough to exceed the threshold for 
acceptance. 


DIFF can handle files with up to 2000 lines. 


DIFF first prompts you for two input file names: the “new’ file, and the 
"old" file. DIFF appends ".TEXT" to these file names, if it is not 
present. DIFF then prompts you for a filename for the listing file. 
Type carriage-return to send the listing to the console. 


DIFF does not (currently) know about INCLUDE files. However, DIFF does 
allow the processing of several pairs of files to be sent to the same 
listing file. Thus, wnen DIFF is finished with one pair o gg it 
prompts you for another pair of input files. To terminate FF, simply 
type carriage-return in response to the prompt for an input el name. 


The output produced by DIFF consists of blocks of "changed" lines. 


Each block of changes is surrounded by a few lines of "context" to aid 
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in finding the lines in a hard-copy listing of the files. 
There are three kinds of change blocks: 


INSERTION -= a block of lines in the "new file which does not 
appear in the "old" file. 


DELETION =~ a block of lines in the "old" file which does not appear 
in the "new" file. 


REPLACEMENT -- a block of lines in the "new" file which replaces a 
corresponding block of different lines in the old file. 


Large blocks of changes are princed in summary fashion: a few lines 
at the beginning of the changes and a few lines at the end of the 
changes, with an indication of how many lines were skipped. 


DIFF has three options which allow you to change the number of context 
lines displayed (+C), the number of lines required to constitute a 
match (+4), and the number of lines displayed act the beginning of a 
long block of differences (+D). To set one of these numbers, 

type the option name followed by the new number to the prompt for 

the first input file name. +D 100, for example, causes DIFF to 

print out up to 100 lines of a block of differences before usin 

an ellipsis. The maximum number of context lines you can get is 8. 
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FINDID 


FINDID searches code files for an identifier. It provides a service 
similar to that of the editor’s literal search, but the search can 
cover any number of files of any size. When executed, it asks first 
for the nase of the file which contains the list of files through which 
you want to search. For example, if you want to search the files 
CODE.TEXT, CODE1.TEXT, and CODE2.TEXT, make a file which contains: 


Code. Text 
Codel.Text 
Code2.Text 


and give FINDID this file’s name. FINDID then asks for the identifier 

you want to search for. Only the first eight characters are significant. 
The search is always literal--any identifier beginning with the specified 
eight characters is considered a match. FINDID’s last prompt asks whether 
the search should ignore case differences. FINDID then grovels through 
files in the list reporting any occurrences of the identifier. To get 

ouc of FINDID, hit NMI, then type RM to LisaBug. 
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Pretty List scans a listing produced by the Assembler, and replaces 

the asterisks in the displacement portion of branch instructions with 
the actual forward reference value. 
are asked for the Inpuc File (the Assembler listing file). 
file can be either a data file or a text file (with a 


the next prompt is: 


PRETTY LIST 


When you X(ecute PRETTY, 
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Because this 
-TEXT extension), 


Tf input file is a text file (file.text) type 1 else type 0 == 


Pretty List then asks for the output file name. 


If the listing file contains: 


0360 

0360; 49FA **** 
0364; 6000 ***x* 
0362* 0006 


Pretty list produces: 


0360| 
0360; 49FA 0006 
0364; 6000 005A 


CHKLO 


CHKLO 


BSR4 
LEA 
BRA 


BSR4 
LEA 
BRA 


CSKMEM 
@1,a4 
CHKMEM 


CHKMEM 
@1,A4 
CHKMEM 
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PAS CALREF 


Pascalref is a cross reference utility for Lisa Pascal programs. 

Ie can perform partial or complete cross references, can handle 

USES and INCLUDE statements correctly, and imposes no limit on the size 
of the target program. 


Pascalref assumes that the program or unit to be referenced (target 
program) has been compiled without syntax errors. It also assumes 
thae the font BOLDIOV and the file MPMENUFILE.TEXT are available on 
your prefix volume or the boot volume (#5:). 


THE USER INTERFACE 


ACTION SEARCHOPTLIONS FINDTYPES YN-TF <= The Menu Bar 
Setup Files Interaccive Beciared Yes-True 
Set Scope Reloffsets Modified No~-False 
Begin Pascalref Procdic Accessed 
Widepaper Stnd PFT 


Used Unie Int 
Out Seope Vars 


The line in capitals at the tep represents the menus in the menu bar. 

The lower case names are the items in each pull down menu. A shaded 

menu item shows that the option represented by that item is active. 

To change the ‘Procdic’ option, for example, use the mouse to select 
“Procdic’ then select either True or False. You can also type SP, then 
enter Y(es or T(rue, N(o or F(alse. When you have all your options set up, 
select ‘Begin Pascalref’. 


OPTIONS 
Setup Files 


You are asked for the names of the listing file, source file, and 
output file. 


Set Scope | 


Pascalref allows you to set the scope to be a single procedure. 
Only identifiers within that procedure and its local procedures are 
teferenced. Of course, accesses to any variables global to the 
procedure are included in the OUT OF SCOPE section. The default 
scope is the whole program. Currently, when referencing a Unit by 
itself, only set the scope to the whole unit. Also, don’t set the 
scope to a FORWARD procedure or a procedure in the interface of a 
unit. 
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Begin Pascalref 


Start the cross reference. 


SEARCHOPTIONS 
Interactive: . 


When Interactive is true (the default), Pascalref looks only for 
those names that occur in the lise of variables that you type in. 


When a particular reference is finished, Pascalref asks you ‘Look at 
more identifiers?’. I£ you answer yes, PascalRef returns to the options 
setting routine wich the same files set up. You can change the options 
and che files on each pass if you want to. 


When Interactive is false, Pascalref cross references all identifiers 
within the specified scope. 


Reloffsets 


Next to each occurrence of an identifier is the line number it occurs 
on. When Reloffsets is true (the defaule), the line numbers are listed 
relative to the procedure the occurrence is in. 


When Relotfsets is false, offsets are given relative to the beginning 
of the program. 


Procdic 


If Procdic is true, Pascalref creates a procedure dictfonary liscing 
each Procedure with the line it starts on. The default for ProcDic is 
false. The program or outermost procedure in the scope is procedure #1. 
Nested procedures are indented. 


In the case of forward procedures and procedures declared in che 
interface of a unit, che procedure number listed reflects where 

the procedure declaration occurs. ‘Forward Proc’ appears in the 
procedure dictionary after the “STARTING LINE #’. The ordered locacion 
of the procedure name and the starting line number within the procedure 
dictionary reflect where the header to the body part of the procedure 
occurs. 


Widepaper 


The default value (False) should be used when sending ourcput to the 
console or to standard 8-1/2 inch wide paper. When printing on 
132 column paper, set Widepaper to true. 
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Used Unit Int 


The default value of True causes the INTERFACE parts of USED units 
to be included in the PASCALREF scan. This allows you to see where 
every identifier used by a Pascal program is defined. If you are 
not interested in the INTERFACE of a unit, set “Used Unit Int’ to 
false. 


Ouc Scope Vars 


When a program accesses a identifier that has not been defined, that 
access shows up in the OUT OF SCOPE VARIABLES OR PROCEDURES section of 
the PASCALREF listing. This part of the listing is present when 

‘Out Scope Vars’ is true (the default). 


FINDTYPES 


The three ‘Find Types’ are DECLARED, MODIFIED and ACCESSED. The 

default value of each type is true. Each type can be set independently. 
When all are true, all occurrences of an identifier are listed. If, for 
example, only ACCESSED is true, PascalRef lists only places where a 
variable is accessed. MODIFIED flags places where a variable occurs 

co the left of :=, and where it is passed as the actual parameter = 
to a formal VAR parameter. DECLARED lists places where an identifier 

is declared. 


Stnd PFT lists occurrences of standard procedures, functions and types. 
Its default is false. 


YN-TF 


This menu gives you an option for answering Yes-No and True-False 
questions. Choosing Yes-True is the same as entering a ‘Y’ or ‘T’ 
from the keyboard and choosing No-False is the same as entering a 


Parse 


au or ‘Fe. 
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OUTPUT FORMAT 


LISTING (Pascalref can produce a listing identical to that produced by 
the compiler) 


PROCEDURE DICTIONARY: 


PROC #, PROC NAME, STARTING LINE # 
L: MAINPROGRAM 0 
3% NESTEDPROC 80 
4: FURTHERNESTEDP ROC 120 
38 PROC 200 
2: FORWARDP ROCWHOSEBODYCOMESAFTERPROC 40=Forward Loc 
6: PROCNE STED INBODYOF FORWARDPROC 280 
7: LAS TGLOBALP ROC 300 


The idencifier we are referencing 

| The procedures it occurs in 

| | The occurrences within those procedures 

| | | 

IDENTIFIE PROCEDURE OCCURRENCE (Dedefined, Asaccessed, Memodified, 


<<< SooSss=e= _----- V=Var param def, P=passed to Var param) 
I PROCA D 10, P 45, A 50, A 60. 
PROCB D 16, A 20, A 30, 
STRNG PROCA D 2, M 41, M 62, A 50, A 58, 
A 60, 
PROCC V 75, M 80, A 82. 


OUT OF SCOPE VARIABLES OR PROCEDURES 


These are listed in the same format as that of the regular identifiess, 
but represent items that are global to the chosen scope. To find our 
what global variables a procedure and its nested procedures access, 

sec the scope to the procedure, set INTERACTIVE to false and look at 
the resulting OUT OF SCOPE items. 


GENERAL NOTES ON THE USE OF PASCALREF 
Pascalref does not store information about variable types or record 
structures. If you have boch a stand alone variable named AYVAR and 
a record field named AVAR, PascalRef lists both as the saze 
identifier. 
Include commands are recognized by Pascalref and the INTERFACE 


parts of units USED by the target program are included in the 
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reference if the scope is set to the whole program. 


To find variables that are declared but no longer used by a progran, 
do a reference of the whole program. Variables that have a “D’ 


eceurrence and ne others can often be removed from the program. 


Occurrences of a particular identifier are always exactly in order 
when interactive is true. When interactive is false, occurrences are 
grouped by the procedures where the identifier is declared locally. 
In the case where interactive is false, you may notice che following: 


I PROCA D 10, P 45, A 50, A 60. 
PROCB D 16, A 20, A 30, 


The variable ‘I’ was declared and accessed in PROCA and declared and 
accessed in PROCB. The accesses in PROCA occur after the declaration 
and accesses in proc B but they are listed first. 


té ‘I’ were noe defined in PROCB, it would look like: 


I PROCA D = 10, 
PROCB A 2,A 30, 
PROCA f - 45, 4-° 30,4 60. 


If the first example were done in interactive mode, it would look like: 


t PROCA D 10, 
PROCB D 16,A 20, A ~~ 30, 
PROCA P 45,4 SO, A 60. 


Procedures and Functions as parameters are currently not fully 
implemented in Pascalref. They are parsed by Pascalref, but 
Variables passed to a procedure or function that is a parameter are 
always marked as modified in that occurrence. 
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DUMPOEJ 


DUMPOBJ is a disassembler for 68000 code. It can disassemble either 
an encire file, or specific modules (procedures) within the file. 
DUMPOBJ replaces DUMPMCODE. 


DUMPOBJ first asks for the input file which should be an unlinked 
object file. The output (listing) file defaults to CONSOLE:. 
You are asked whether you want to dump 


A(11, S(ome, or Particular modules. 


16-Feo-82 


If you respond S(ome, DUMPOBJ asks you for confirmation before dumpiag 


each module. A response of <ESC> gets you back to the top level. If 


you respond P(articular, DUMPOBJ asks you for the particular module(s) 


you wane dumped. 


The next question is: “Dump file positions (N]?’ The file position 
is a number of the form [0,000] where che first digit is the block 
number (decimal) within the file and the second number is the byte 
number (hexadecimal) within the block at which the module starts. 
This informacion can be used in conjunction with the PATCH program. 
Finally, DUMPOBJ asks if you wane the object code disassembled. 
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Pi 


DUMPHEX 


DumpHex provides a textual representation of the contents of any file. 

The file dump is block=-oriented with the nexadecimal representation on 

the left and the corresponding ASCII representation on the right. If 

a byte cannot be converted to a printable character, a dot is substituted. 


When DumpHex is X(ecuted, it asks you for the name ef the cutput file. 
A .TEXT extension is added if necessary. To direct the output to the 
console, type carriage return. After getting a valid output file name, 
DumpHex asks for the input file to be dumped. No extensions are 
appended, so give the full filename. Once a file has been completely 
dumped, DumpHex asks you for the next file to duzp. Type carriage 
return to exit the program. 


After opening the input file, DumpHex asks you which block to dump. 

The default (carriage return) is block 0. If the output is going to 
a file, you are asked which block is the last you want dumped. The 

default here (carriage return) is the last block in the file. 


The format of the console output depends on the number of lines your 
screen nas. If fewer than 33 lines are available, the output is 
displaved only a half block at a time. Between blocks or block 
halves you have the option to 


Type <space> to continue, <escape> to exit. 


Escape returns to the prompt for an input file. 
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PATCH 


Patch allows you to examine and change the contents of any file. The 
display of the file’s contents is exactly like that of DumpHex. With 
Patch, however, you can use the cursor control keys to move around in 
the block and change the value of any byte using either the hexadecinal 
representation on the left or the ASCII represencation on the right. 


After X(ecuting Patch you are asked for che full name of the file to 
patch. Carriage return exits Patch. No extension is appended to the 
file name. You are then asked for the number of the block you want 
to mess around with. Carriage return here returns you to the file 
mame prompt. 


The block is displayed with the cursor in the upper left corner at 
word QO of the block. The arrow keys can be used to move around in 
the block. If you move the cursor up from the top line, you get the 
bottom line of the preceding block. Similarly, if you move down 
from the bottom line, you move into the top line of the next block. 


When the cursor is on the hexadecinal side of the display, you can 
change any byte by typing the new hexadecimal value. Any non-hex 
characters are ignored. You can impress your friends by pointing 
out that the change is reflected aucomatically in the ASCII portion 
of the display. When the cursor is on the ASCII side, type any 
character to replace the value of the byte. Uncil you move out of 
the block you can undo any changes by typing <escape>. 
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OBJDIFF 
OBJDIFF performs a comparison of two object (.0BJ) files. The two 
files being compared should be very similar. OBJDIFF uses procedure 
poundaries to get itself back in syne after a difference is found. 
BYTEDIFF 
BYTEDIFF compares any binary files, but once it finds a difference 
between the two files, it does not always find where the differences 
end. 
GXREF 
GXREF lists all the modules which call a given procedure, and all the 


modules which that procedure calls. It provides a global cross reference 
of subroutines and modules. 
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LISATEST 


LISATEST is a package of hardware test routines. The DLAG: diskette 
which contains these programs can be obtained from Rich Castro. To use 
the programs, boot the Apple [I with the Lisa in the power-on reset 
state, then X(ecute LISATEST. You have eight choices: 


1) Apple-Lisa Interface Tesc 
2) Memory Tese (RAMTEST) 

3) Display Memory Test Results 
4) UART Wrap Around Test 

5) Video Latch Test 

6) MMU Test 

7) Reyboard Tese 


9) Quit 


The tests are, for the most part, self-explanatory. For a complete 
description of each test, its prompts, error messages, and options 
please see the Lisa Production Tests documentation by Rich Castro. 
A short description of each test is given telow. 


Apple-Lisa Interface Test 

The Interface Test attempts to use the parallel port interface between 
the Apple Il and the Lisa to verify that the two systems can communicate 
with each other. 

Memory Test 

The Memory Test program tries to single out bad or marginal memory chips 
and provides trouble shooting information about other memory board 


problems. It is essentially an updated and easy to use version of 
RAMTEST. 


Display Memory Test Results 


After running the Memory Test, you can have the results of that test 
redisplayed by che Display Memory Test Results progran. 


UART Wrap around Test 

The UART Test checks the UART on the CPU board chaz concrols the 2$-232 
port #1 (the one on the left as you face front of the machine). To run 
the test you need a specially wired wrap around D8-25 male connector. 


Video Latch Test 


The Video Latch Test checks the operation of the video page latch on che 
MCU board. 
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MMU Test 
The MMU Test tries to verify that the MMU is working properly. it sets 


up the base and limit registers in the MMU with various values and then 
attempts to access the corresponding memory segments.~ 


Keyboard Test 


The Keyboard Test checks the keyboard and mouse buttons to verify that 
the COPS interfaces are functioning properly. 
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PERFORM 


Perform monitors the execution performance of a program. After X(ecuting 
Perform, you are asked for the listing file’s name. A carriage return 
directs output to the console. [If necessary, .TEXT is appended to the 
listing file name. You are next asked for the name of the program 

you want to analyze. If necessary, the extension .OBJ is added to 

the file name. The program file must be executable and must te 

linked with the corresponding .DBG files. 


Perform scans the program file for procedure entry points, listing them 
as they are found. It then waits for you to type a space before executing 
the program. Every 1/60 second the program’s program counter is checked 
to find out which routine is executing at that moment. When the program 
terminates, Perform produces a listing of the routines it found executing 
ordered according to the amount of time spent in each routine. Routines 
that were never caught executing are listed separately. Perform may miss 
the execution of short or rarely called routines. 


The longer the program runs, the more trustworthy the analysis. Routines 
that are synchronous with the 60 Hz clock are not measured correctly. 

Tf M.SYMBOLS is included, PERFORM also gives information on the 

amount of time spene in the monitor (“PASLIB). 
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COVERAGE ANALYSIS 


The CA program provides a coverage analysis of a Lisa Pascal program. Branch 
counters are inserted into the source (.TEXT file) of the program under test. 
The output of the CA program is then compiled and linked. At the end of 

the progran’s execution, a text file is produced giving the branch numbers 
and the number of times each branch was executed. 


To run the coverage analysis program you need to get the sources of any of 
the units and programs you want to analyze and the -OBJ versions of any 
other units that are required to link the program. You should be able to 
compile and link these sources without error. To add counters to a unit 
Or progran: 


X(ecute CA 
CA first asks for the name of the source file: 
Input file = 


Give it the name of the file you want analyzed. The output of CA is another 
source file containing the original source modified by the addition of the 
counters and the analysis machinery. The output file can be very large, so 
give it plenty of room. 


Output file - 


The name you give here is the name of the new source (with the branch 
counters added in). 


The next prompt is: 
Count B(ranches, P(rocedures, O(ne unit 


You can count every branch (every THEN, ELSE, CASE branch, REPEAT, DO, etc), 
just procedure entries, or just report on the branch counters in a unit that 
has already been run through CA. If you ask that every branch be counted, CA 
also asks: 


Routine to skip (<cr> for none): 


The compiler has a fixed code buffer size. If a procedure in the original 
program is close to the size limit, it may be impossible to add counters 
to every branch and still compile that procedure. The compiler error is 
#350, “procedure too large". If you add the counters and the compiler 
complains about some procedure, run CA again, and give the of fending 
procedure name here. If more than one procedure is too large, either 
complain to the developers, or ask someone to make the “roucine=to-skip’ 
code take a list of names. 


The next prompt was Pete Cressman’s idea: 


Enable tracing? 
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Type ‘y’ and every time the program is executed you will be asked if you 

want to be informed about every procedure entry during execution of the 

program. This avalanche of names can be very tedious to watch. If you 
wey 


respond ''n'’, the tracing machinery is omitted from the program and you are 
never asked whether it should be activated. 


The next prompt is: 
Data file = 


The data file is the file containing the coverage analysis after the program 
has executed. It is a text file, so you can read it with the mouse editor. 
You can match each counter number up with the code ic is counting by 
examining the output file that CA produces. At each branch you will find 

a procedure call of the form: 


_CA_Inc(n); 


where n is the counter number. AL1 objects added by CA to the program 
start with the the four letters ‘_CA_’ to try to avoid naming conflicts. 


Finally, you are given a chance to place some arbitrary sequence of text 
in the header of the data file (date of the test, or whatever). Type <cr> 
to end the comments. 


If you are adding counters to a unit, some of these questions are omitted 
because they are irrelevant. . 


Once CA has added the counters, you must compile the output file, generate 
the .OBJ file, and link it with all the units it requires. If all goes 
well, each time you execute the program the data file is updated. [If che 
data file does not exist, it is created. If it does exist, the counter 
daca it contains are added to the current counter values. The resulting 


data file therefore contains a record of an arbitrary number of program 
executions. 


If you get the Linker warning: 
Segment <mumble> too large 


you will have to break that segment into two pieces, write a procedure to 
force the new segment to be resident whenever the old one was, and start 
over with the CA program. The problem here is that a segment can contain 
mo more than 32 Kbytes of code or data. There is no way the CA program can 
tell when a segment is close to the limit. If a segment is right on the 
dorderline, it is not inconceivable that the branch counters will cause iz 
to overflow. , 


The counters pin at 32767. Programs that run ia the Window Manager-OS 
anvironment are recognized, and theoretically correct code is issued, 
Dut no promises are made yet. CA increases the size of both the source 
«TEXT file and the final .OBJ file by about 30 vercenc. I: aay slow 
execution rates noticeably. 
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SCRIPT 
SCRIPT is Colin McMaster’s text formatting programe SCRIPT commands ws 
are: 
Nane Default Example Effect 
Page Length 66 “pl N Define page length to be N lines 
Page Number 1 “pa N Start page numbering at N 
Page Break _ “bp Start a new page 
Need Lines — “ne N Make sure at least N lines remain on page 
Line Space 1 “ils 1 Set single or double spacing 
Space 1 “sp N Space N lines 
Break Line = “bE Start a new line 
Page Offset 0 “po N Start leftmost printing at column N 
Indent 0 “in N Indent N columns from page offset 
Temporary Indene 0 "ti N Indent N columns for next line only 
Right Margin 72 “ra N Set line length to N characters 
Fill =< ap 0 Set filling mode to true 
No Fill — “nt Set filling mode to false 
Justify = “ad Justify texe to right margin 
No Justify _ “na Turn justification off 2 
Center 1 “ce N Center next N lines 
Text -- “ex ‘N Display N literally 
Change command == “ce N Change SCRIPT command character to N 
Title _ “el ‘L‘C’R Prine titles Left, Center, Right 
Margin 1 4 “al N Set number of lines above and including header «= 
Margin 2 2 “m2 N Set number of lines below header 
Margin 3 2 “m3 N Set number of lines above and including footer \ 
Margin 4 4 “m4 N Set number of lines below footer 
Header = “he ‘L‘C’R Place headers Left, Center, Right 
Even Header -= “eh ’L’C’R Place even headers Left, Center, Right 
Odd Header _— “oh ‘L’C’R Place odd headers Left, Center, Right 
Footer - “fo ’L’C’R Place footers Left, Center, Right 
Even Footer =< “ef ’L’C’R etc 
Odd Footer = “of “L°C"R 
Source _ “so ‘File’ Begin printing text of File 
Zero Slash = “zs Turn on zero slashing 
No Zero Slash == “nz Turn off zero slashing 
Keywords — “kw Underline Pascal keywords 
No Keywords — “nk Do not underline Pascal keywords 
Define Macro = “de VO Begin definition of macro VO 
Terminate Macro = = End definition of macro 
Append Macro = “am VO Append to macro VO 
Delete Macro —_ “dm VO Delete macro VO 
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SCRIPT OPTIONS (specified when SCRIPT is executed) 


eC Change command character to C 

“fFILE Send output to FILE (.TEXT is not appended for you) 

“k Underline Pascal keywords 

-1 Assume output is going to a Printronix-style printer 

man Start page numbering ac N 

“oLIST Output only the pages given in LIST 

-p Assume printer has full control of page 

“q Assume output is going to a Qume-like printer 

-s Stop printing after each page and wait for <er> or <ESC> 
-2zN Set page offset to N 


This version of Script does not attempt to recurn to its top level when 
it has finished with a file. Because it is trying to exit the program 
from a unit, it usually quits with “fatal error 1’. Do not use the 
options that refer to printers. To see your formatted text, use either 
“S or -F. 


More complete documentation is available from Publicacions. 
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TERMINAL EMULATOR 


Files needed: TERM OB! 
LISA: SYSTEM.FONT 
LISA: TERM .MENUS 
LISA: SARA&F 


The terminal emulator (TERM) provides a Lisa folder which is a full duplex 
virtual terminal. The terminal control commands implemented here are 
similar to those of the Hewlett-Packard 2640 and 2645, the DataMedia, 
Perkin-Elmer Fox and Owl, Beehive, and the DEC VT=-52 terminals, as well 

as the "VTS2" modes of the DEC VT-100 and HeathKit H19 terminals. 


e terminal emulator works only with che "new Lisa hardware. addition, 

Ne back of the 

fer of the visible board 

wer supply should already have the 

de raised. For the terminal 
so be raised. 


machine and 
(the I0 board). Thee 
LOth pin from the bote 
emulator 


To invoke the emulator, copy the files given above, and X(ecute TERM. 
The emulator has three menus and a tray icon. The Speed menu sets the 
baud rate. Available speeds are 300, 600, 1200, 2400, 4800, 9600, and 
19200 baud. 600 baud is not available on Port #1. The default speed 
is 300 baud. 


The Port Menu determines which serial port is connected to the modem. 
Pore #1 is the connector in the center. Port #2 is the connector nearest 
the power supply. The default port is #2. 


The control menu has four items: Record, Play Back, Debug, and Quic. If 
you select Record, all characters received by the UART are saved in the 
file RECORD.TEXT. If you select Play Back, the contents of the file 
PLAYBACK. TEXT are sent to the UART just as if they had been typed. If you 
want to see exactly what characters are being received, including control 
characters and escape sequences, select Debug. To exit the terminal 
emulator, select Quit. 


The control commands are: 


Cerl-G Bell (screen flashes ) 

Cerl-H Backspace 

Ctrl-1 Tab (8 spaces) 

Cteri-J Linefeed 

Cerl=M Carriage return 

Cerl-[ Start Escape Sequence (see below) 
Escape-¢ Enter Insert Character Mode 
Escape-A Cursor Up 

Escape-3 Cursor Down 

Escape~C Cursor Right 

Escape-D Cursor Left 

Escape-i Clear screen 

Escape-H Cursor home (top left corner) 
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Escape-i 
Escape-J 
Escape-K 
Escape=L 
Escape-M 
Escape-N 
Escape-0 
Escape=P 


Escape-Y 


Escape=) 
Escape-j 
Escape~k 
Escape-l 
Escape-o 
Escape-p 
Escape-q 
Escape-z 


Seroll down 

Clear to end of screen 

Clear to end of line 

Insert line position 

Delete line position 

Delete character position 

Leave Insert Character Mode 

Insert character position 

Absolute character positioning (Y+31, X+#31) 
Clear to beginning of screen 

Save Cursor position 

Restore saved cursor position 
Erase line 

Clear to beginning of line 

Stand out (bold characters) 

Reset Stand Out (normal characters) 
Initialize terminal 


All other Escape and Control sequences are ignored. 


ua. 
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ERROR MESSAGES 


There are several error categories--1/0 errors, Loader errors, 
trap handler errors, and Pascal Compiler errors. In most cases, 
you can type SPACE to return to the Monitor command line. Since 
nothing in the Monitor is tied to the user stack pointer, the 
Monitor can usually recover from errors that are fatal in the 


Apple II UCSD system. 


The Monitor’s globals are hidden beneath 


the heap, and the Monitor code itself sits above your code 
space, so both are somewhat protected from inadvertent destruction. 


a oe 
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I/O ERRORS 


No error 

Bad Block (Parity error) 

Bad device number 

Bad mode (Illegal operation) 
Undefined hardware error 
Lost device 

Lost file 

Bad file name 

No room 

No device 

No file 

Duplicate file 

File not closed before open. 
File not open 

Bad format 

Ring buffer overflow 
Write-protect error 

Device error 


LOADER ERRORS 


Unknown segment 

No room in memory 

Bad block 

Can’t read code file 

Jump table overflow 

SecSP at wrong place (after a shysical link) 
This loader does not handle intrinsic unizs 
Too many units 

Bad unit number 

No INTRINSIC.LIB file 

No unit Llocacion table 

No segment location table 

Cannot open intrinsic segment file 

Cannot read file names block 
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ATAL ERRORS 


rey 


Illegal index at trap handler 
Stack Overs low 

Programmed Halt 

Range value error 

Illegal string index 

Can’: read Root Volume 


PASCAL COMPILER ERRORS 


Lexical Errors: 


Too many digits 

Digit expected after ’.’ in real 
Integer overflow 

Digit expected in exponent 


End of line encountered in string constant 


Illegal character in input 


Premature end of file in source program 
Extra characters encountered after end of program 


End of file encountered in a comment 


Syntactic Errors: 


20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 


Tllegal symbol 

Error in simple type 
Error in declaration part 
Error in parameter list 
Error in constant 

error in type 

Error in field lise 
Error in factor 

Error in variable 
Identifier expected 
Integer expected 

’(’ expected 
expected 
“(’ expected 
‘|’ expected 

:° expected 
3; expected 
=" expected 
» e&xpecced 

“®’ axpected 

“:=° expected 

‘program’ expected 

‘of’ expected 

‘begin’ expected 

“and’ expected 

‘then’ expected 

‘until’ expected 

‘do’ expected 

‘to’ or ‘downto’ expected 
‘file’ expected 
“i£° expected 
“.’ expected 
‘implementation’ expected 
‘interface’ expected 
“intrinsic” expected 
“shared’ expected 


. 
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Semantic Errors: 


100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
lll 
112 
ap) 
L1lé 
115 


116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
? 126 


127 
128 
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Idencifier declared twice 

Identifier not ‘of the appropriate class 

Identifier not declared 

Sign not allowed 

Number expected 

Lower bound exceeds upper bound 

Incompatible subrange types 

Type of constant must be integer 

Type must not be real 

Tagfield mist be scalar or subrange 

Type incompatible with with tagfield type 

Index type must not be real 

Index type must be scalar or subrange 

Index type must not be ‘integer’ or ‘longint’ 
Unsacified forward reference 

Forward reference type identifier cannot appear in variable 
declaration 

Forward declaration - repetition of parameter list not allowed 
Forward declared function ~ repeticion of result type not allowed 
Function result type must be scalar, subrange, or pointer 
File value parameter not allowed 

Missing result type in function declaration 

Feformat for real only 

Error in type of standard function parameter 

Error in type of standard procedure parameter 

Nuaber of parameters does not agree with declaration 
Illegal parameter substitution 

Result type of parameteric function function does not agree with 
declaration 

Expression is not of set type 

Only tests on equality allowed 

Strict inclusion not allowed 

File comparison not allowed 

Illegal type of operand(s) 

Type of operand must be Boolean 

Set element type must be scalar or subrange 

Set element types not compatible 

Type of variable is not array or string 

Index type is not compatible with declaration 

Type of variable is not record 

Type of variable must be file or pointer 

Illegal type of loop control variable 

Illegal type of expression 

Assignment of files not allowed 

Label type incompatible with selecting expression 
Subrange bounds must be scalar 

Type conflict of operands 

Assignment to standard function is not allowed 
assignment to formal function is not allowed 

No such field in this record 

Type error in read 
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149 
150 
151 
2 252 
153 
2? 154 
155 
156 
157 
158 
159 
160 
? 161 
162 
163 
164 
165 
166 
167 
168 
169 
170 
171 
172 


190 


Actual parameter must be a variable 

Multidefined case label 

Missing corresponding variant declaration 

Real or string tagfields not allowed 

Previous declaration was not forward 

Substitution of standard proc/fune is not allowed 
Multidefined label 

Multideclared label 

Undefined label 

Undeclared label 

Value parameter expected 

Mulcidefined record variant 

File not allowed here 

Unknown compiler directive (not ‘excernal’ or ‘’forward’) 
Variable cannot be packed field 

Set of real is not allowed 

Fields of packed records cannot be var parameters 
Case selector expression aust be scalar or subrange 
String sizes aust te equal 

String too long 

Value out of range 

Address of standard procedure cannot be taken 
Assignment to function result must be done inside that function 
Loop control variable must be local 


No such unit in this file 


Cenditional Compilation: 


260 
261 
262 
263 
264 
265 
266 
267 


New compile-time variable must be declared at global level 
Underined compile-time variable 

Error in compile-time expression 

Conditional compilation options nested too deeply 
Unmatched ELSEC 

Unmatched ENDC 

Error in SETC 

Unternminated conditional compilation option 


Compiler Specific Limitations: 


300 
301 
302 
303 
304 
305 
306 
307 
308 


350 
351 


Too many nested record scopes 

Sec limits out of range 

String limits out of range 

Too many nested procedures/functions 

Too many nested include/uses files 
Tacludes not allowed in interface section 
Pack and unpack are not implemented 

Too many units 

Set constant out of range 


Procedure too large 
File name in option too long 
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400 Not enough room for code file 
401 Errer in rereading code file 
402 Error in reopening text file 
403 Unable te open uses file 

404 Error is reading uses file 

ror in opening include file 
or in rereading previously read text block 
Not enough room for i=code file 
in writing code file 

409 Error in reading i-code file 
410 Unable co open listing file 

420 1/0 error on debug file 
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Code Generation Errors: 


1000+ Code generator errors - should never occur 


2000 End of I=code file not found 

2001 Expression too complicated, code generator ran out of registers 
2002 Code generator tried to free a register that was already free 
2003-2005 Error in generating address 

2006=2010 Error in expressions 

2011 Too many globals 

2012 : Too sany locals 


Verification Errors: 


4000 Bad verification block format 
4001 Source code version conflict 
4002 Compiler version conflicre 
4003 Linker version conflict 


4100 Version in file less than minimum version supported by program 
4101 Version in file greater than maximum version supported by progran 
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ASSEMBLER ERRORS 


Q. 
Lis 
2. 
3. 
4. 


6. 
7. 


undefined label 

operand out of range 

must have procedure name 

number of parameters expected 

extra garbage on line 

fnput line over 80 characters 

not enough .IF’s 

must be declared in .ASECT before used 
identifier previously declared 
improper format 

eEQU expected 

must .EQU before use if not to a label 
macro identifier expected 

word addressed machine 

backward .ORG currently noe allowed 
idencifier expected 

constant expected 

invalid structure 

extra special symbol 

branch too far 

variable noc PC relative 

illegal macro parameter index 

not enough macro parameters - 

operand not absolute 

illegal use of special symbols 
ill-formed expression 

not enough operands 

cannot handle this relative expression 
constant overflow 

illegal decimal constant 

tllegal octal conscance 

illegal binary constant 

invalid key word 

aacro stack overflow - 5 nested limit 
include files may not be nested 
unexpected end of input 

this is a bad place for an .INCLUDE file 
only labels & comments aay occupy col 1 
expected local label 

local label stack overflow 

string constant aust be on one line 
string constant exceeds 80 characters 
fllegal use of macro parameter 

no local labels in .ASECT 

expected key word 

string expected 

bad block, parity error (CRC) 

bad unit number 

bad mode, illegal operation 

undefined hardware error 

lose unit, unic is no longer on-line 
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Lowreowod 


52. 
53. 
54. 
55. 
56. 
57. 
58. 
5$. 
60. 
6l. 
62.6 
63. 
64. 
65. 
66. 
67. 
68. 
69. 
70. 
71. 
72. 
73. 
74. 
75. 
76. 
Ts 
78. 
rhe 
80. 
81. 
82. 
83. 
84. 
85. 
86. 


osc pees Sy sise ces 


lost file, file is no longer in directory 
bad citle, illegal file name 

no room, insufficient space on disk 

no unit, no such volume on-line 

no file, no such file on volume 
duplicate file 

not closed, attempt to open an open file 
not open, attempt to access 4 closed fil 
bad format, error in reading real or int 
nested macro definitions illegal 

‘s’ or ‘<>’ expected 

may not EQU to undefined labels 

must declare .ABSOLUTE before Ist - PROC 


Net even a register 

Not a Data Register. 

Not an Address Register 

Register Expected 

Right Paren Expected 

Right Paren or Comma Expected 
Unrecognizable Operand 

Odd location counter 

Unimplemented Motorola directive 
Comma Expected. 

One operand must be a data register. 
Dn,Dn or -(An),-(An) expected. 

No longs allowed. 

First operand must be immediate. 
First operand must be Dn or #E 

(Ant), (An+) expected 

Second operand must be an An 

Second operand must be a Dn 
#<data>,Dn expected. 

first operand must be a Dn- 

An, #<displacement> expected 

An is not allowed with byte 

only alzerable addressing modes allowed 
only data alcerable addr modes allowed 
An is not allowed 

USP, SR, and CCR not allowed 

Cannot move from CCR 

Dx,d(Ay) or d(Ay),Dx expected. 

Only memory alterable addr modes allowed 
Only control addressing modes allowed 
Must branch backwards to label 
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SOFT. 
GUIDES 


ALAIN ROSSMANN November 10, 1983 
Ext 4088 


This note details all the things to Keep in mind when writing an 
application to make it easily localizable. It assumes a certain 
familiarity with the technical documentation of Macintosh. Some of the 
features mentioned here may not be fully documented at this time in 
the technical documentation. 


DRAFT 


SOFTWARE LOCALIZATION GUIDELINES 


The time of global markets has come. Why not increase the sales of 
your program by selling it into international markets ? These markets 
are developing very fast and are expected to grow at a higher rate 
than the US market. 


To reach these markets your product needs to be fully localized. It 
can achieve a good penetration in international markets only if its 
users can understand it : having localized products is the Key to 
success in international markets. 


Macintosh unique localization technology allows you to sharply -reduce 
the cost of localizing your product to foreign markets. Macintosh 
provides you with the ideal set of tools to create international 
products. 


In order to get the maximum benefit from these tools, your program 
must be conceived from the ground up with international markets in 
mind. In particular, your program must make systematic use of 
Resources for Menus, Dialogs, Alerts, and formats. 


The tools that Macintosh provides you are : predefined Resources for 
Menu Bars and Menu Items, Dialog Boxes, Alert Boxes, formats (number, 
currency, time, date), resource editor, Keyboard editor, software 
packages for compares, time and date display, number and currency 
display, number input. 


Macintosh is a graphically oriented machine. The use of icons greatly 
enhances and simplifies the interaction with the user. From an 
international standpoint, it also simplifies the localization process. 
Icons are international, they don’t have to be translated. 


Use icons as much as possible. A good example is MacPaint where most 
of the commands are accessible by clicking on an Icon. Macintosh 
provides you with an Icon editor to create your own Icons, which can 
then be stored in your application resource file. 


Translating software can be a difficult and expensive process: the 
translator has to "dive" into the code to translate a program and do 


the layout changes required. Macintosh totally solves this problem by 
using resources. 


TOOLS 


Resources enable you to save most of the country dependent features of 
your program into a separate entity. This resource can then be easily 
modified through the resource editor. The resource editor is not only 


a very powerful development tool, but also the most flexible 
localization tool. 


With the Resource Editor any non technical person can access the 
Dialogs, Alerts, and Menus of your program and modify them on the 
screen, in real time. The Resource Editor is completely graphically 
oriented, for example dialog zones can be grown by selecting them, 
clicking in their grow box, and draging the box. There are no 
coordinates to compute, no counting of dots. ** Will be available 
early 84, alpha versions for dialogs exist** 


SOFTWARE DESIGN 


Menu Items, Menu Bars, Dialogs, and Alert Boxes should always te put 
into your application resource file. This will allow a non technical 
person to translate, resize, and change the layout of dialog boxes, 
without Knowing anything about the actual code of your application. 
Text in Dialogs, Alerts, and Menus can be edited the same way any text 
is edited on Macintosh. Translation simply consists in selecting the 
text, replacing it by the translated text, changing the layout to fit 
the size of the new text. Upon exiting of the resource editor, the 
localized program is immediately functional, no recompilation is 
necessary. 


Your application should never rely on the length or position of 
strings in Menus or Dialogs. Different languages will have different 
word length and different word order. If your program is dependent aon 


some string length or string order it won’t work properly when 
translated. 


LOCALIZATION 


If the localization is performed by a third party, you don’t have toa 
give them your source code. This helps you Keep complete control over 
your product. The resource editor runs on a Macintosh: no other 
equipment is meeded for the localization phase of the program. Once a 
dictionary of common terms has been built, most programs can be fully 
translated in less than an hour by a non technical person. 


CHARACTER SET AND KEYBOARDS 


—————————e——_—e—_e—_—_— — ee ee eee ae ee we es ee ee we we we we we we we oe es oe we ew oe ee es ae ee 


Foreign countries use characters that do not appear in the standard 
ASCII character set. This can lead to lots of problems when selling 
products in International markets. 


TOOLS 


On Macintosh, there is only one character set for all the countries 
which use Latin characters. This character set is common to Macintosh 
and Lisa. It contains all the characters needed for the major 
countries plus special characters and mathematical symbols (See 
Appendix 1 for the character set). 


The character set defines the one byte codes that internally represent 
each character. Thus all the Macintoshes in all the countries use the 
same internal code for all the characters. Note that all the bits are 
used in the one byte code that defines a character. 


Fonts contain the bit pattern that defines the shape of a specific 
character on the screen. Fonts are contained in a special type of 
resource. Some fonts may not include bit patterns for all the 
characters **the foreign characters may not be always there**. The 
system font will always have all the characters. 


If you feel stronaly that your application must have complete fants, 
it can have its private fonts. 


The only thing that differs from country to country is the way 
characters are generated. Each country has its own Keyboard ( See 
Appendix 2 for Keyboard layouts). The whole character set can be 
generated from any Keyboard. The only difference is that the keys to 
type in order to generate a certain character may not be the same in 
different countries. 


The option Key is used to access the characters which are not shown on 
the Keycaps. Accents are not characters by themselves. They are 
generated by pressing dead keys. When a dead key is pressed it does 
not generated any character. If the accute accent is typed, for 
example, nothing happens until the next character is typed. This 
character will be accented with an accute accent. 


Please note that Keyboards have no way of identifying themselves. GUnly 
the Keyboard mapping is changed to go from one keyboard to another. 


The Keyboard desk accessory allows you toa look at the option Keyboard. 
It also enables you to remap your Keyboard, that is to redefine what 
character is generated when a certain combination of Keys is pressed 
#*® remapping is not yet implemented. 


SOFTWARE DESIGN 


Do not use the 8th bit in the ASCII code to store information, it is 
used in our extended character set. Your program should not access the 
Keyboard directly. As long as it uses the toolbox routines to do so, 
foreign Keyboards will be transparent to your application. 


Some menu commands may have Keyboard equivalents in your application. 
Be sure to put these commands in the Menu Item definition Resource so 
that it can be easily edited through the Resource Editor. 
LOCALIZATION 

It is easy to overlook Keyboard equivalents during the translation 


process. Be sure to explain how they have been chosen to the person 
who will translate your program. 


Having accented characters in the character set poses specific 
problems when comparing strings. There is a compare routine in-ROM to 
handle compares. 


TOOLS 

The routine comes in four flavors determined by two boolean flaqs. The 
first flag is “ignore case", the second is " ignore diacritical 
marks". 


If the “ignore case" flag is set, the comparison will be true 
regardless of the cases of the two characters compared. Likewise, if 
the “ignore diacritical" flag is set, the compare will be true 
regardiess of the accentuation of the two characters being compared. 
If both flags are reset, the compare is an ASCII compare, if both 
flags are set it matches characters regardless of their cases and 
accentuation. - 


SOFTWARE DESIGN 
Be sure to use the right Kind of compare although it may not make a 
difference in your language. For example a simple Word processor may 


provide an “ignore everything" compare although there are no 
diacritical marks in your language. 


Different countries use different formats for numbers, currencies, 
time, date, measure units. They also have different ways of sorting 
lists. This can lead to lots of problems when an application is ported 
to another country. Macintosh gives a very elegant,yet powerful 


solution to this problem through the use of the resources INTLO and 
INTLI. 


TOOLS 


These resources contain information concerning number format, currency 
format, date format, time format, use of metric or English format, 
sorting. This information is stored in two predefined resource types : 
INTLO and INTL1. 

(See Appendix 4 for the map of INTLO and INTL1). 


INTL1 contains the information needed to display expanded dates and to 
sort. You can save space by omitting INTL1 when expanded dates and 
sorting are not needed. 


A set of routine which allow you to add INTLO and INTLi to your 
program are provided to make it easier to implement INTLO or INTLi1. 
They may be completed by a set of access routines to allow Pascal 
programs to easily access the information in INTLO and INTL1 **May not 
be written#*., 


SOFTWARE DESIGN 


Each time your application uses anything related to these items , it 
must either call the appropriate routine provided in our software 
packages or directly look into the resources to get the necessary 
information. 


If you use our packages, you don’t need to Know the detailed structure 
of INTLO and INTL1. We provide packages which cover : number and 
currency display, time and date display, magnitude compare for 
sorting, number input. Number and currency input and output are 
included in the arithmetic package **May not be written. 


Be careful to look into INTLO to get the number separator if you don’t 
use our number input package. The number separator should also be used 
for list of numbers as they may appear in a function having multiple 
arguments. 


As for any other resource, INTLO and INTL1 can live at any of these 
three levels : in the System Resource File, in the Application 
Resource File, and in the Document Resource File. Resources Files will 
automatically be searched for INTLO or INTL1 in the following order : 
Document Resource File, Application Resource File, System Resource 
Files. 


At the developer’s choice there can be an INTLO or INTLi resource in 
the application resource or in the document resource. There wil! 
always be a copy of INTLO and INTLi in the system resource file ¢a 


that it can be used as a default if your application does not have its 
private version of INTLO and INTLIi. 


Having your own version of INTLO or INTL1 in your application’s 
Resource File, allows your application to remember its formats 
independently from the disk it is moved to. If documents have their 
own version of INTLO or INTLi, they will Keep the same format even if 
they are used under a foreign version of the application. 


A calendar for example may not need to have its private version of 
INTLO or INTLI, It is sufficient for this type of application to look 
into the System Resource to get the necessary format information. 


A program using dates may want to display dates according to the 
language used in its Dialogs. To achieve that it must have an INTLO in 
its Resource File, so that the date formats are linked to the 
application and not to the disk. 


A Spreadsheet where numbers can be displayed as currencies would put 
INTLO with each document. Data integrity has to be preserved : it is 
not acceptable to have amounts labeled in Dollars suddenly displayed 
as Francs because a different version of the application is used. 

There must be an INTLO in each document resource file. Upon creation 


of the document, the default formats can be read from the application 
INTLO. 


If the structure of your documents depends on the sorting sequence, 
INTL1 must be included in the document resource file. An example of 
that is a binary tree 

where part of the structure information is in the file itself and the 
rest in the magnitude compare. 


LOCALIZATION 


INTLO and INTL1i ¢ except for sorting) are easily modified through the 
resource editor. This allows user to customize their formats, provided 
that your program makes systematic use of these resources. 


It allows you to produce masters for each country that have the proper 
formats on them (See Appendix 3 for the most common formats in each 
country). 


Of course if you feel that users of your program must be able to 
modify these formats “on the fly" , you can include a routine that 
directly modifies INTLO or INTLi from within your program. An example 
of that would be for a wordprocessor to offer the capability to switch 
from English to Metric rulers from within the application. 
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The Character Set 
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NON-PRINTING 
ASCIT NON-ASCIT 


ae Symbol for a non-breaking space. Prints a blank character, same width as numbers. 
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C/T JC 


US 
UK 


Germany 


Erance 


-.aly 


Days 


Month 


mm/dd/yy 
dd/mm/ yy 
dd.mm.yry 
dd/mm/ yy 


dd/mm/aa 


US/UK 


Monday 
Tuesday 
Wednesday 
Thursday 
Friday 
Saturday 
Sunday 


January 
February 
March 
April 
May 

June 
July 
August 
September 
October 
November 
December 
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Dates Formats 


Date 
3/31/83 6/3/83 
31/03/83 03/06/83 
31.03.83 3.06.83 
31/03/83 3/06/83 
31/03/83 03/06/83 
Germany France 
Montag Lundi 
Dienstag Mardi 
Mittwoch Mercredi 
Donnersdag Jeudi 
Freitag Vendredi 
Sonnabend Samedi 
Sonntag Dimanche 
Januar Janvier 
Februar feyvrier 
Mkrz mars 
April avril 
Mai mai 
Juni Juin 
Juli Juillet 
August aout 
September septembre 
Oktober octobre 
November novembre 
Dezember decembre 


Expanded date 


Thursday March 31, 1983 


Thursday March 31, 1983 
Donnerstag den 31. Marz 1983 


Jeudi 31 mars 1983 


gioved?i 31 Maggio 1983 


Italy 


luned) 
martedt} " 
mercoledi 
giovedi 
venerdi 
sabato 
domenica 


Gennaio 
Febbraia 
Marzo 
Aprile 
Maggio 
Giugno 
Luglio 
Agosto 
Settembre 
Ottobre 
Novembre 
Dicembre 


US 


Time 11:30 am 
7:05 am 


11:20 pm 
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Time Formats 


UK Germany 
11:30 11.30 Uhr 
09:05 9.05 Uhr 


23:20 23.20 Uhr 


France 


11:30 


7:05 


23:20 


Italy 


11,30 
9,05 


23,20 


us 
Number 1,234,567.89 
Decimal 0.9876 
number 
Separator  <----- ,occc-- 


Cassumes that 
numbers are entered 
without separators 
ather than the 
decimal point ) 


Example: Number 1=4132.2 


Number 2=3.14159 
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Number formats 


UK 


1,234,567.89 


0.9876 


Separator= "," ¢uUS) 
"3" ¢€Germany) 


Germany/Italy 


0,9876 


1.234.567,89 


9123.2 , 3.14159 entered from the keyboard for US 


9123,2 3; 3,14159 entered from the Keyboard for Germany 


France 
1 234 567,89 


0,9876 
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Currency representation 


us UK Germany France Italy 
aocurrency symbol $0.23 £0.23 0,23 DM 0,23 F L. 0,23 
egative ($0.23) 0.23) - 0,23 DM - 0,23 F LIT. -0,23 
Without decimal $345.00 9 345 325,00 DM 325 F L. 345 


Note : 
Thousand separators and decimal point are the same in currency 
representation as in numbers 
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FP68K DOCS 


SUMMARY OF FP68K DOCUMENTS 1 


User's Guide -- an overview of FP68K ELEMS68K and their design philosophy. 
Programmer's Guide -- hints on how to build the packages, and 
how to modify them, if necessary; details about system 
dependencies involving the state areae- Includes register 
map templates. 
System Interface -- how FP68K and ELEMS68K affect their execution environment. 
High-Level Interface -- the SANE Pascal unit and assembly macros. 
Integer Conversion Tests 
Binary-Decimal Conversion Tests 
IEEE Tests -- a set of test vectors designed for this style of 
arithmetic and distributed through the standards 
subcommittee 
Binary-—Decimal Conversions -- what is available through the SANE 
interface, and what FP68K provides at the low level. 
A sample parser and formatter from the SANE interface 


is shown. 


P754 stuff -- papers related to the arithmetic standard. 
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SUMMARY OF FP68K FILES 


FPxxx.TEXT -- source files for FP68K, except for binary-decimal 
conversions 

FBxxxe TEXT -- source files for binary-decimal part of FP68K 

SAxxx. TEXT -- SANE68.TEXT -- SANE interface section 


SAIMP68.TEXT -- SANE implementation section 
SAASM68.TEXT -- SANE assembly procedures 
SAMAC68.TEXT -- EQU's and MACRO's for assembly interface 


DOxxx-TEXT -~- documentation using SCRIPT formatter, with 
macros in DODRIVER. TEXT 


TVxxx.TEXT -- IEEE test vector files, required operations 
TWxxx. TEXT -- IEEE test vector files, appendix funtions 
TDxxx. TEXT -- Test vector driver program files 

ITxxx. TEXT -- integer <--> extended conversion tests 
I0xxx. TEXT -- binary <--> decimal conversions tests 
Zyyyy-OBJ -- executable test programs 


ELxxx. TEXT -- elementary transcendental and financial functions 
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Introduction 


The 68000 software floating-point packages, FP68K and ELEMS68K, appear 
much like simple subroutines but their interaction with the host system is 
somewhat more subtle. This document indicates possible trouble spots. It is 
intended for system implementors, rather than users of FP68K and ELEMS68K. 


The following sections describe the various issues in turn. 


Registers and stack used 


FP68K and ELEMS68K receive all of their parameters on the stack. They 
save and restore all of the CPU registers across calls, except that DO is 
modified by the REMAINDER operation. FP68K modifies the CPU Condition Code 
Register as described later. 


As detailed in the "Program Notes" document, FP68K typically uses up to 
41 words of stack beyond the input parameters. The only exceptions are the 
binary-decimal conversion and nextafter routines, which may use up to 120 
words beyond the input parameters. ELEMS68K uses at most 30 words of stack 
for temporary storage. 


Single entry point 


FP68K has just one entry point -- with the label 'FP68K'. When invoked, 
FP68K expects the return address on the stack, followed by a one-word opcode 
described in the user's guide. Beyond the opcode are up to three operand 
addresses (depending on the operation). Note that because the operands are 
passed by address, they must be in memory, NOT IN THE REGISTER FILE. 


If FP68K is to be invoked by a mechanism like the A-line trap, care must 
be taken that stack is set up properly. Depending on the system, it should be 
possible to execute FP68K either as a subprogram linked to an application 
program, or as system-provided utility. 


Because of the varying number of input parameters, it is impossible to 
call FP68K directly from Pascal, since the number of parameters is fixed when 
the EXTERNAL procedure is defined. In any case programmers should use the 
provided Pascal interface, called SANE (Standard Apple Numeric Environment). 


ELEMS68K has a similar design, but is configured as a separate package 
for modularity. 


Exit points 


Typically, FP68K exits by clearing all input operands from the stack and 
jumping to the return address. 
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However, a ‘halting’ mechanism is provided whereby control is transferred WJ 
from FP68K to an address saved in the floating-point state area (see below). 
This address should refer to a subprogram in the user's code space. When the 
halt routine is invoked, the top of the stack is a word containing the number 
of bytes of parameters (including the return address) on the stack when FP68K 
was originally called. Beyond that word is the exact stack frame from when 
FP68K was originally called. 


ELEMS68K has no built-in halt mechanism, though a subsidiary FP68K 
operation may halt. 


State area 


ELEMS68K maintains no static state. FP68K maintains 3 words of static 
state across invocationse The first word contains mode and flag bits, much 
like the CPU Status Register. The next long word is the user trap address. 
There are two important issues: where is the state area and how is it 
initialized? 


The state area may be a fixed area in memory, as in MAC, or at a fixed 
offset from a register like A6, as in LISA, or in some user area if FP68K is 
linked as a subroutine. The state area may even be kept within FP68K itself, 
though this makes the code self-modifying and thus NON-REENTRANT. 


In multi-process environments, care must be taken to see that different 
state areas are kept for the different processes (again, think of the CPU . 
Status Register). For example, if the state area is kept in a fixed location 
in memory, it must be swapped each time a new process is swapped in. 


The location of the state area must be known at ASSEMBLY TIME. As 
indicated in the programmer's guide document, the code must be set up for the 
particular host environment. 


When a new process is started up, the state area must be initialized. 
Fortunately, this is easy. Just clear to 0 the first word of the state area 
(ieee the mode and flag word). 


CPU Condition Code Register 


The Comparison operation leaves the CCR in a well-defined state. After 
Comparison, the CCR is set for a conditional branch, although the flags are 
used in a way different from the integer CPU comparisons; see the "User's 
Guide" for details. 


CPU Register DO 


The Remainder operation leaves the low-order integer quotient (between 
-127 and +127) in DO.W. The high half of DO.L is undefined. This intrusion 
into the register file is extremely valuable in argument reduction -- the 
principal use of Remainder. The state of DO after an invalid remainder is WJ 
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f undefined. 
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SANE 


There is a SANE (Standard Apple Numeric Environment) library of utility 
functions based on FP68K, as well as a corresponding Elems library based on 
ELEMS68K. These libraries are supported on Apple III Pascal systems as well. 
The library provides access to the package from (Lisa) Pascal. Aside from 
support of basic arithmetic and elementary functions, the utilities manipulate 
the modes and flags and provide ASCII <--> floating-point conversions. All 
applications software should use this package because of its high degree of 
portability. 


Assembly language programmers will invoke FP68K and ELEMS68K directly but 
will depend on some library for routines to convert between ASCII strings and 
the canonical decimal format which FP68K recognizes. A set of mnemonic MACROS 
has been provide to expedite assembly coding. 


Compiling Pascal programs 


A Pascal program which exploits the SANE and Elems interfaces must 
include lines such as 


uses {SU <some volume>:SANE.OBJ} SANE; 

uses {$U <some volume>:ELEMS.OBJ} Elems; 
in order to gain access to the types and procedures defined there. Then the 
program must be linked with SANE.OBJ and ELEMS.OBJ (the Pascal parts of the 
interface), as well as SANEASM.OBJ and ELEMSASM.OBJ (the assembly language 
parts of the interface). 


Pascal procedures 


Programmers should consult the INTERFACE section of the SANE and Elems 
interfaces (files SANE.TEXT and ELEMS. TEXT) in the following pages. This 
interface reflects the architecture discussed in the "User's Guide". It is 
two-address, with the destination operand in the extended format except for 
format conversions conversions. 


Macros 


A set of macros provides direct contact with the arithmetic package, 
using the interface described in the "Yser's Guide". The macros take care of 
the opcode and the JSR, but the programmer must explicity push the required 
argument addresses. The macros do not take effective address arguments and 
push them itself because of the problems that arise if the destination operand 
is given as an offset from SP (which changes when the first operand address is 
pushed). The macros are listed after the Pascal interface. 
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Sample program 


The test programs ITxxx.TEXT, I0xxx.TEXT, and TDFP.TEXT provide a 
nontrivial view of how to use the Pascal interface to FP68K and ELEMS68K. 


1 November 83 


SANE Interface 8 


{*he ''SANE Interface'' } WwW 
{*fo '28 December 1982'Page Z'Apple Confidential’ } 

{$C Copyright Apple Computer, 1982 } 

{MacIntosh versione} 


UNIT Sane; 
INTERFACE 
CONST 
SIGDIGLEN = 20; { Maximum length of SigDig. } 
DECSTRLEN = 80; { Maximum length of DecStr. } 
TYPE 
{---------------------------~--~+----------------------------------- 
** Numeric types. 
a ee ele ee eS } 
Single = array [0..1] of integer; 
Double = array [0..3] of integer; 
Comp = array [0..3] of integer; 
Extended = array [0..4] of integer; 
ae teen earn e 
** Decimal string type and intermediate decimal type, 
** representing the value: 
aK (-1)*sgn * 10*exp * dig 
a a a } 
SigDig = string [SIGDIGLEN]; 
DecStr = string [DECSTRLEN]; 
Decimal = record 
sgn : Ooel; { Sign (0 for pos, 1 for neg). } 
exp : integer; { Exponent. } 
sig : SigDig { String of significant digits. } 
end; 
{“ne 16 } 


** Modes, flags, and selections. 

** NOTE: the values of the style element of the DecForm record 
** have different names from the PCS version to avoid name 

** conflicts. 


a } 
Environ = integer; 
RoundDir = (TONEAREST, UPWARD, DOWNWARD, TOWARDZERO); 
RelOp = (GT, LT, GL, EQ, GE, LE, GEL, UNORD); 
{> < ©) = >= <= <=> } 
Exception = (INVALID, UNDERFLOW, OVERFLOW, DIVBYZERO, WW 
/ INEXACT) ; 
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NumClass = (SNAN, QNAN, INFINITE, ZERO, NORMAL, DENORMAL); 
DecForm = record 
style : (FloatDecimal, FixedDecimal); 
digits : integer 
end; 
} 
[ine eee eee anemones 
** Two address, extended-based arithmetic operations. 
a erence ele eat et } 
procedure AddS (x : Single; var y : Extended); 
procedure AddD (x : Double; var y : Extended); 
procedure AddC (x : Comp; var y : Extended); 
procedure AddX (x : Extended; var y : Extended); 
{y :=y+x } 
procedure SubS (x : Single; var y : Extended); 
procedure SubD (x : Double; var y : Extended); 
procedure SubC (x : Comp; var y : Extended); 
procedure SubX (x : Extended; var y : Extended); 
iyi ype x] 
procedure MulS (x : Single; var y : Extended); 
procedure MulD (x : Double; var y : Extended); 
procedure MulC (x : Comp; var y : Extended); 
procedure MulX (x : Extended; var y : Extended); 
ty wy Fay 
procedure DivS (x : Single; var y : Extended); 
procedure DivD (x : Double; var y : Extended); 
procedure DivC (x : Comp; var y : Extended); 
procedure DivX (x : Extended; var y : Extended); 
{y :=y /x} 
function CmpX (x : Extended; r : RelOp; 
y : Extended) : boolean; 
{x ry } 
function RelX (x, y : Extended) : RelOp; 
{ x RelX y, where RelX in [GT, LT, EQ, UNORD] } 
} 
ith a in Ss ene aaa ann a iene fe ain maaan eel 
** Conversions between Extended and the other numeric types, 
** including the types integer and Longint. 
ee eS } 


procedure I2X (x : integer; var y : Extended); 

procedure S2X (x : Single; var y : Extended); 

procedure D2X (x : Double; var y : Extended); 

procedure C2X (x : Comp; var y : Extended); 

procedure X2X (x : Extended; var y : Extended); 
{ y := x (arithmetic assignment) é 
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procedure X2I (x : Extended; var y : integer); 
procedure X2S (x : Extended; var y : Single); 
procedure X2D (x : Extended; var y : Double); 
procedure X2C (x : Extended; var y : Comp); 
{ y := x (arithmetic assignment) } 
{---------------------~-------------------------------------------- 


*k These conversions apply to 68K systems only. Longint is 
** ga 32-bit two's complement integer. 


procedure L2X (x : Longint; var y : Extended); 
procedure X2L (x : Extended; var y : Longint); 
{ y := x (arithmetic assignment) } 


** Conversions between the numeric types and the intermediate 
** decimal type. 


-<--------- wo --- - - - = = = - - - - - - - - - - =} 


procedure S2Dec (f : DecForm; x : Single; var y : Decimal); 
procedure D2Dec (f : DecForm; x : Double; var y : Decimal); 
procedure C2Dec (f : DecForm; x : Comp; var y : Decimal); 
procedure X2Dec (f : DecForm; x : Extended; var y : Decimal); 


{ y := x (according to the format f) } 


procedure Dec2S (x : Decimal; var y : Single); 

procedure Dec2D (x Decimal; var y : Double); 

procedure Dec2C (x Decimal; var y : Comp); 

procedure Dec2X (x : Decimal; var y : Extended); 
{y i= x} 


oo ee ee 


** Conversions between the numeric types and strings. 
** (These conversions have a built-in scanner/parser to convert 
** between the intermediate decimal type and a string.) 


procedure S2Str (f : DecForm; x : Single; var y : DecStr); 

procedure D2Str (f : DecForm; x : Double; var y : DecStr); 

procedure C2Str (f : DecForm; x : Comp; var y : DecStr); 

procedure X2Str (f : DecForm; x : Extended; var y : DecStr); 
{ y := x (according to the format f) } 


procedure Str2S (x : DecStr; var y : Single); 

procedure Str2D (x : DecStr; var y : Double); 

procedure Str2C (x : DecStr; var y : Comp); 

procedure Str2X (x : DecStr; var y : Extended); 
Ly se a9 
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{*ne 31 } 
(Steet eee ear ee een een peon eee 
** Numerical 'library' procedures and functions. 
a te } 
procedure RemX (x : Extended; var y : Extended; 
var quo : integer); 
{ new y := remainder of ((old y) / x), such that 
|new y| <= |x| / 2; 
quo := low order seven bits of integer quotient y / x, 
so that -127 <= quo <= 127. 
procedure SqrtX (var x : Extended); 
{ x := sqrt (x) } 
procedure RintX (var x : Extended); 
{ x := rounded value of x } 
procedure NegX (var x : Extended); 
{ x := -x } 
procedure AbsX (var x : Extended); 
{ x := |x| } 
procedure CpySgnX (var x : Extended; y : Extended); 
{ x := x with the sign of y } 
procedure NextS (var x : Single; y : Single); 
procedure NextD (var x : Double; y : Double); 
procedure NextX (var x : Extended; y : Extended); 
{ x := next representable value from x toward y } 
function ClassS (x : Single; var sgn : integer) : NumClass; 
function ClassD (x : Double; var sgn : integer) : NumClass; 
function ClassC (x : Comp; var sgn : integer) : NumClass; 
function ClassX (x : Extended; var sgn : integer) : NumClass; 
{ sgn := sign of x (0 for pos, 1 for neg) } 
procedure ScalbX (n : integer; var y : Extended); 
{ y := y * 2°n } 
procedure LogbX (var x : Extended); 
{ returns unbiased exponent of x } 
{*ne 16 } 
[het err ee ees ancien aan neeenc enamine 
** Manipulations of the static numeric state. 
a a ee } 
procedure SetRnd (r : RoundDir); 
procedure SetEnv (e : Environ); 
procedure ProcExit(e : Environ); 
function GetRnd : RoundDir; 
procedure GetEnv (var e : Environ); 
procedure ProcEntry (var e : Environ); 
function TestXcp (x : Exception) : boolean; 
procedure SetXcp (x : Exception; OnOff : boolean); 
function TestHlt (x : Exception) : boolean; 
procedure SetHlt (x : Exception; OnOff : boolean); 
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{$I SANEIMP. TEXT} 
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{$C Copyright Apple Computer Inc., 1983 } 
UNIT Elems; 


{ Macintosh version. } 


INTERFACE 
USES 
{SU OBJ:SANE.OBJ } 
SANE { Standard Apple Numeric Environment } ; 


procedure Log2X (var x : Extended); 
{ x := log2 (x) } 


procedure LnX (var x : Extended); 
{ x := ln (x) } 


procedure LnlX (var x : Extended); 
{ x := 1n (1 + x) } 


procedure Exp2X (var x : Extended); 
{ s2 S= 27x} 


procedure ExpX (var x : Extended); 
{ x := e*x } 


procedure ExplX (var x : Extended); 
{ x := e*x - 1 } 


procedure XpwrI (i : integer; var x : Extended); 
{ x := xi } 


procedure XpwrY (y : Extended; var x : Extended); 
{ x := x*y } 


procedure Compound (r, n : Extended; var x : Extended); 
{ x := (1 + r)*n } 


procedure Annuity (r, n : Extended; var x : Extended); 
{x := (1 - (1 + r)*-n) / r } 


procedure SinX (var x : Extended); 
{ x := sin(x) } 


procedure CosX (var x : Extended); 
{ x := cos(x) } 


procedure TanX (var x : Extended); 
{ x := tan(x) } 
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procedure AtanX (var x : Extended); 
{ x := atan(x) } 


procedure NextRandom (var x : Extended); 
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{ x := next random (x) } 
(Spec ere a re } 
IMPLEMENTATION 
procedure Log2X { (var x : Extended) } ; EXTERNAL; 
procedure LnX { (var x : Extended) } ; EXTERNAL; 
procedure LnlX { (var x : Extended) } ; EXTERNAL; 
procedure Exp2X { (var x : Extended) } ; EXTERNAL; 
procedure ExpX { (var x : Extended) } ; EXTERNAL; 
procedure ExplX { (var x : Extended) } ; EXTERNAL; 


{ 


Since Elems implementation expects pointer to integer argument, 


use this extra level of interface. 
} 
procedure XpwrIxxx(var i : integer; var x : Extended); 
procedure Xpwrl { (i : integer; var x : Extended) } ; 
begin 
Xpwrixxx(i, x); 
end; 


procedure XpwrY { (y : Extended; var x : Extended) } ; 


procedure Compound { (r, n : Extended; var x : Extended) } ; EXTERNAL; 


EXTERNAL; 


EXTERNAL; 


procedure Annuity { (r, n : Extended; var x : Extended) } ; EXTERNAL; 


procedure SinX { (var x : Extended) } ; EXTERNAL; 
procedure CosX { (var x : Extended) } ; EXTERNAL; 
procedure TanX { (var x : Extended) } ; EXTERNAL; 
procedure AtanX { (var x : Extended) } ; EXTERNAL; 
procedure NextRandom { (var x : Extended) } ; EXTERNAL; 
END 
{saeaesssssassssSSSS SSS SaaS SSS SSeS SS SSS SSeS SSS SSS SSS SS SSS SSS SSS SSS SSSSSS= } 
{ === SS SS ES eS SS SE SS SS SS SS SS SS SS SE SE SE SS SE SS SE SE SS SSS SSS SSS SSS SS SS SS SS SE SES SS } 
{seessessssasassssses ss sa as SSS SSeS SSS SSS SS SSS SSS SSS SSS SSS SSS SSS SS SSS SSSS= } . 
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FP68K and ELEMS68K Macros 


> 

> 

; These macros give assembly language access to the Mac 

; floating-point arithmetic routines. The arithmetic has 
3 just one entry point. It is typically accessed through 
3 the tooltrap FP68K, although a custom version of the 
package may be linked as an object file, in which case 
the entry point is the label ZFP68K. 


All calls to the arithmetic take the form: 


PEA <source address> 

PEA <destination address> 
MOVE.W <opcode>,-(SP) 
_FP68K 


© Wo we we we we we wo Ve we 


All operands are passed by address. The <opcode> word 
specifies the instruction analogously to a 68000 machine 
instruction. Depending on the instruction, there may be 
from one to three operand addresses passed. 


This definition file specifies details of the <opcode> 
word and the floating point state word, and defines 
some handy macros. 


Modification history: 
29AUG82: WRITTEN BY JEROME COONEN 
130CT82: FB CONSTRANTS ADDED (JTC) 
28DEC82: LOGB, SCALB ADDED, INF MODES OUT (JTC). 
29APR83: ABS, NEG, CPYSGN, CLASS ADDED (JTC). 
O3MAY83: NEXT, SETXCP ADDED (JTC). 
28MAY83: ELEMENTARY FUNCTIONS ADDED (JTC). 
04JUL83: SHORT BRANCHES, TRIG AND RAND ADDED (JTC). 
O1NOV83: PRECISION CONTROL MADE A MODE (JTC). 


we we we we Ve we we we we we Oe we we we we we we Ew 


Se eS a SE A a SS SY 


; This constant determines whether the floating point unit 
3 is accessed via the system dispatcher after an A-line 

3; trap, or through a direct subroutine call to a custom 

3 version of the package linked directly to the application. 


ATRAP - EQU 0 30 for JSR and 1 for A-line 
BTRAP -EQU 0 30 for JSR and 1 for A-line 

«MACRO JSRFP 

IF ATRAP 

_FP68K 

- ELSE 

- REF FP68K 

JSR FP68K 

- ENDC 

«ENDM 
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eMACRO JSRELEMS 


2 IF BTRAP 
_ELEMS68K 

ELSE 

»REF | ELEMS68K 
JSR ELEMS68K 
~ENDC 

.ENDM 


° i a a a 


3 

; OPERATION MASKS: bits SOOI1F of the operation word 

: determine the operation. There are two rough classes of 
; operations: even numbered opcodes are the usual 

; arithmetic operations and odd numbered opcodes are non= 
; arithmetic or utility operations. 


. ee SOOO 


FOADD ° EQU $0000 
FOSUB e EQU $0002 
FOMUL e EQU $0004 
FODIV -EQU $0006 
FOCMP - EQU $0008 
FOCPX 2EQU $SOO0A 
FOREM e EQU $000C 
FOZ2X 2EQU SOOOE 
FOX2Z e EQU $0010 
FOSQRT °EQU $0012 
FORTI ° EQU $0014 
FOTTI e EQU $0016 
FOSCALB e EQU $0018 
FOLOGB eEQU SOO1LA 
FOCLASS 2 EQU $O01C 
; UNDEFINED °EQU SOOLE 
FOSETENV ° EQU $0001 
FOGETENV -EQU $0003 
FOSETTV eEQU $0005 
FOGETTV eEQU $0007 
FOD2B - EQU $0009 
FOB2D -EQU $000B 
FONEG - EQU $000D 
FOABS -EQU SOOOF 
FOCPYSGNX » EQU $0011 
FONEXT -EQU $0013 
FOSETXCP - EQU $0015 
FOPROCENTRY 2 EQU $0017 
FOPROCEXIT e EQU $0019 
FOTESTXCP - EQU SOO1B 
; UNDEFINED - EQU $001D 
; UNDEFINED -EQU SOOLF 
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3; OPERAND FORMAT MASKS: bits $3800 determine the format of 
3 any non-extended operand. 


FFLNG 


$8000 


$6000 


$1F00 


$0080 


$0060 


; SOOLF 


the state word. 


3 extended -- 80-bit float 


; double —- 64-bit float 
; Single -- 32-bit float 
3 integer -- 16-bit integer 
; long int -- 32-bit integer 
3 accounting -- 64-bit int 


Bit indexes for error and halt bits and rounding modes in 
The word is broken down as: 


unused 

rounding modes 

$0000 -- to nearest 

$2000 -- toward t+infinity 
$4000 -- toward -infinity 
$6000 -- toward zero 
error flags 

$1000 -- inexact 

$0800 -- division by zero 
$0400 -- overflow 

$0200 -- underflow 

$0100 -- invalid operation 


result of last rounding 
$0000 -- rounded down in magnitude 
$0080 -- rounded up in magnitude 


precision control 
$0000 -- extended 
$0020 -- double 
$0040 -- single 


$0060 -- ILLEGAL 


halt enables, corresponding to error flags 


3 The bit indexes are based on the byte halves of the state 


3 word. 


FBUFLOW 
FBOFLOW 
FBDIVZER 
FBINEXACT 
FBRNDLO 
FBRNDHI 
FBLSTRND 
FBDBL 
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invalid operation 
underflow 

overflow 

division by zero 

inexact 

low bit of rounding mode 
high bit of rounding mode 
last round result bit 
double precision control 
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FBSGL - EQU 6 ; single precision control 

gm nn 
; FLOATING CONDITIONAL BRANCHES: floating point comparisons 
; set the CPU condition code register (the CCR) as follows: 
; relation XNZVC 

Pd 

: equal 00100 

: less than 11001 

; greater than 00000 

: unordered 00010 

; The macros below define a set of so-called floating 

: branches to spare the programmer repeated refernces to the 
; the table above. 


eae ce meee a a a He A A a AE A SS A A a a ee A A Se a a EE SS SS a 


. 


BEQ 41 

e ENDM 

«MACRO FBLT 
BCS val 

e ENDM 

eMACRO FBLE 
BLS hl 

e ENDM 

eMACRO FBGT 
BGT val 

- ENDM 

eMACRO FBGE 
BGE ral 

« ENDM 


BLT hl 

e ENDM 

»MACRO FBULE 
BLE 4’ 

- ENDM 


BCC Zl 
- ENDM 
«MACRO FBU 
BVS val 
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a 


«ENDM 


e MACRO 
BVC 
- ENDM 


» MACRO 
BNE 
« ENDM 


»MACRO 
BEQ 
BVS 
e ENDM 


e MACRO 
BNE 
BVC 

- ENDM 


3 Short branch 


«MACRO 
BEQ.S 
- ENDM 


» MACRO 
BCS.S 
«ENDM 


«MACRO 
BLS.S 
- ENDM 


«MACRO 
BGT.S 
- ENDM 


«MACRO 
BGE.S 
« ENDM 


»MACRO 
BLT.S 
« ENDM 


«MACRO 
BLE.S 
« ENDM 


«MACRO 


BHI.S 
- ENDM 
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FBO 
val 


FBNE 
val 


FBUE 
val 
Z1 


FBLG 
hl 
Zl 


versions. 
FBEQS 
al 


FBLTS 
hl 


FBLES 
at 


FBGTS 
a1 


FBGES 
hl 


FBULTS 
1 


FBULES 
‘1 


FBUGTS 
hl 
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FBUGES 
%1 


; OPERATION MACROS: 


; THESE MACROS REQUIRE THAT THE OPERANDS' ADDRESSES 

; FIRST BE PUSHED ON THE STACK. 
THEMSELVES PUSH THE ADDRESSES SINCE THE ADDRESSES 
MAY BE SP-RELATIVE, IN WHICH CASE THEY REQUIRE 


PROGRAMMER CARE. 


the stack, with the destination address on top. 
suffix X, D, S, or C determines the format of the source 
; operand -- extended, double, single, or computational 
3; respectively; the destination operand is always extended. 


> 
> 
3 
; OPERATION MACROS: operand addresses should already be on 
> 
H 
> 
> 
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FADDX 
#FFEXT+FOADD,-(SP) 


FADDD 
#FFDBL+FOADD,-(SP) 


THE MACROS CANNOT 


The 
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«MACRO FADDS 

MOVE.W #FFSGL+FOADD,-(SP) 
JSRFP 

- ENDM 


«MACRO FADDC 

MOVE.W #FFCOMP+FOADD,-(SP) 
JSRFP 

«ENDM 


«MACRO FSUBX 

MOVE.W #FFEXT+FOSUB,-(SP) 
JSRFP 

« ENDM 


«MACRO FSUBD 

MOVE.W #FFDBL+FOSUB,-(SP) 
JSRFP 

- ENDM 


eMACRO FSUBS 

MOVE.W #FFSGL+FOSUB,-(SP) 
JSRFP 

+» ENDM 


»MACRO FSUBC 

MOVE.W #FFCOMP+FOSUB,-(SP) 
JSRFP 

- ENDM 


Se A a A a a we 


SE A Se 


eMACRO FMULX 
MOVE.W #FFEXI+FOMUL,-(SP) 


«MACRO FMULD 
MOVE.W #FFDBL+FOMUL,-(SP) 


«MACRO FMULS 
MOVE.W #FFSGL+FOMUL,-(SP) 
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eMACRO FMULC 
MOVE.W #FFCOMP+FOMUL,-(SP) 


eMACRO FDIVX 
MOVE.W #FFEXT+FODIV,-(SP) 


eMACRO FDIVD 
MOVE.W #FFDBL+FODIV,-(SP) 


eMACRO FDIVS 
MOVE.W #FFSGL+FODIV,-(SP) 


«MACRO FDIVC 
MOVE.W #FFCOMP+FODIV,-(SP) 


Se ee ee EE SE A ES SE SS Ee 


«MACRO FCMPX 

MOVE.W #FFEXT+FOCMP,-(SP) 
JSRFP 

-« ENDM 


eMACRO FCMPD 

MOVE.W #FFDBL+FOCMP,-(SP) 
JSRFP 

- ENDM 


«MACRO FCMPS 

MOVE.W #FFSGL+FOCMP,-(SP) 
JSRFP 

e ENDM 


«MACRO FCMPC 

MOVE.W #FFCOMP+FOCMP,-(SP) 
JSRFP 

. ENDM 
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; Compare, signaling invalid operation if the two operands 
3 are unordered. 

eMACRO FCPXX 

MOVE.W #FFEXT+FOCPX,-(SP) 


eMACRO FCPXD 
MOVE.W #FFDBL+FOCPX,-(SP) 


eMACRO FCPXS 
MOVE.W #FFSGL+FOCPX,-(SP) 


»MACRO FCPXC 
MOVE.W #FFCOMP+FOCPX,-(SP) 


; Remainder. The remainder is placed in the destination, 
; and the low bits of the integer quotient are placed in 
3 the low word of register DO. 

«MACRO FREMX 

MOVE.W #FFEXT+FOREM,-(SP) 


«MACRO FREMD 
MOVE.W #FFDBL+FOREM,-(SP) 


«MACRO FREMS 
MOVE.W #FFSGL+FOREM,-(SP) 


«MACRO FREMC 
MOVE.W #FFCOMP+FOREM,-(SP) 


3; Compare the source operand to the extended format and 
; place in the destination. 
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MACRO 
MOVE.W 
JSRFP 
e ENDM 


e MACRO 
MOVE.W 
JSRFP 
e ENDM 


e MACRO 
MOVE.W 
JSRFP 
« ENDM 


e MACRO 
MOVE.W 
JSRFP 
o ENDM 


«MACRO 
MOVE.W 
JSRFP 
« ENDM 


e MACRO 
MOVE .W 
JSRFP 
« ENDM 


FX2X 
#FFEXT+FOZ2X,-(SP) 


FD2X 
#FFDBL+FOZ2X, -( SP) 


FS2X 
#FFSGL+FOZ2X,-( SP) 


FI2X 
#FFINT+FOZ2X,-(SP) 


FL2X 
#FFLNG+FOZ2X, -( SP) 


FC2X 
#FFCOMP+FOZ2X,-( SP) 


; l6—-bit integer 


3; 32-bit integer 


> 
; Convert the extended source operand to the specified 
; format and place in the destination. 
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FX2D 
#FFDBL+FOX2Z,-( SP) 


FX2S 
#FFSGL+FOX2Z,-(SP) 


FX21 
#FFINT+FOX2Z,-( SP) 


FX2L 
#FFLNG+FOX2Z,-(SP) 


3; l6é-bit integer 


; 32-bit integer 
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-ENDM 

«MACRO FX2C 

MOVE.W #FFCOMP+FOX2Z,-(SP) 
JSRFP 

- ENDM 


Miscellaneous operations applying only to extended 
operands. The input operand is overwritten with the 
computed result. 


we 


we 


Square root. 
«MACRO FSQRTX 
MOVE.W #FOSQRT,-(SP) 
JSRFP 
- ENDM 


Round to integer, according to the current rounding mode. 
eMACRO FRINTX 
MOVE.W #FORTI,-(SP) 
JSRFP 
«ENDM 


Round to integer, forcing rounding toward zero. 
«MACRO FTINTX 
MOVE.W #FOTTI,-(SP) 
JSRFP 
- ENDM 


Set the destination to the product: 
(destination) * 2*(source) 
where the source operand is a 16-bit integer. 
«MACRO FSCALBX 
MOVE.W #FFINT+FOSCALB,-(SP) 
JSRFP 
- ENDM 


Replace the destination with its exponent, converted to 
the extended format. 

«MACRO FLOGBX 

MOVE.W #FOLOGB,-(SP) 

JSRFP 

- ENDM 


Negate. 
-MACRO FNEGX 
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MOVE.W #FONEG,-(SP) | 
JSRFP UW 
. ENDM 


; Absolute value. 
»MACRO FABSX 
MOVE.W #FOABS,-(SP) 
JSRFP 
e ENDM 


Copy the sign of the destination operand onto the sign of 
; the source operand. Note that the source operand is 
modified. 

eMACRO FCPYSGNX 

MOVE.W #FOCPYSGN,-(SP) 

JSRFP 

- ENDM 


we 


The nextafter operation replaces the source operand with 
its nearest representable neighbor in the direction of the 
destination operand. Note that both operands are of the 
the same format, as specified by the usual suffix. 
eMACRO FNEXTS 
MOVE.W #FFSGL+FONEXT,-(SP) { 


eMACRO FNEXTD 
MOVE.W #FFDBL+FONEXT,-(SP) 


«MACRO FNEXTX 

MOVE.W #FFEXTI+FONEXT,-(SP) 
JSRFP 

- ENDM 


ce a cr ec ce a a a a ee ne ee ee ee ee ee ee 


; The classify operation places an integer in the 

; destination. The sign of the integer is the sign of the 
; source. The magnitude is determined by the value of the 
3 source, as indicated by the equates. 


Se es a ce ee ce a ee me es ae a ce ee ee ce a ee a ee ee a ee ee ee ee 


FCSNAN -EQU 1 ; Signaling NAN 

FCQNAN - EQU 2 3 quiet NAN 

FCINF -EQU 3 3; infinity 

FCZERO -EQU 4 3; zero 

FCNORM -EQU 5 3 normal number 

FCDENORM -EQU 6 ; denormal number a) 
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«MACRO 
MOVE.W 
JSRFP 
- ENDM 


«MACRO 
MOVE.W 
JSRFP 
- ENDM 


«MACRO 
MOVE.W 
JSRFP 
- ENDM 


«MACRO 
MOVE.W 
JSRFP 
- ENDM 
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FCLASSS 
#FFSGL+FOCLASS ,-(SP) 


FCLASSD 
#FFDBL+FOCLASS, -(SP) 


FCLASSX 
#FFEXT+FOCLASS, -( SP) 


FCLASSC 
#FFCOMP+FOCLASS , -( SP) 


These four operations give access to the floating point 
state (or environment) word and the halt vector address. 
The sole input operand is a pointer to the word or address 
to be placed into the arithmetic state area or read from 


it. 


eS A 


eMACRO 
MOVE.W 
JSRFP 
- ENDM 


«MACRO 
MOVE.W 
JSRFP 
- ENDM 


«MACRO 
MOVE.W 
JSRFP 
- ENDM 


»MACRO 
MOVE.W 


FGETENV 
#FOGETENV ,-( SP) 


FSETENV 
#FOSETENV, -(SP) 


FGETTV 
#FOGETTV, -(SP) 


FSETTV 
#FOSETTV, -( SP) 


Both FPROCENTRY and FPROCEXIT have one operand -- a 
pointer to a word. The entry procedure saves the current 
floating point state in that word and resets the state 

to 0, that is all modes to default, flags and halts to 
OFF. The exit procedure performs the sequence: 
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: 1. Save current error flags in a temporary. 
; 2. Restore the state saved at the address given by 
; the parameter. 
; 3. Signal the exceptions flagged in the temporary, 
;: halting if so specified by the newly 
: restored state word. 
; These routines serve to handle the state word dynamically 
$ across subroutine calls. 

eMACRO FPROCENTRY 

MOVE.W #FOPROCENTRY ,-(SP) 

JSRFP 

e ENDM 


eMACRO FPROCEXIT 

MOVEeW #FOPROCEXIT,-(SP) 
JSRFP 

e ENDM 


a ee SS A A a A EE NE 


3 
; FSETXCP is a null arithmetic operation which stimulates 
; the indicated exception. It may be used by library 
; routines intended to behave like elementary operations. 
; The operand is a pointer to an integer taking any value 
; between FBINVALID and FBINEXACT. 
; FTESTXCP tests the flag indicated by the integer pointed 
; to by the input address. The integer is replaced by a 
; Pascal boolean (word $0000=false, $0100=true) 

«MACRO FSETXCP 

MOVE.W #FOSETXCP,-(SP) 

JSRFP 

e ENDM 


eMACRO FTESTXCP 

MOVE.W #FOTESTXCP,-(SP) 
JSRFP 

- ENDM 


cae es es es me ae ee ee a a me re ee ee a ee ee a ee ee a ee a ee ae ee ee ee 


; WARNING: PASCAL ENUMERATED TYPES, LIKE THOSE OF THE 

; DECIMAL RECORD, ARE STORED IN THE HIGH-ORDER BYTE OF THE 
; ALLOCATED WORD, IF POSSIBLE. THUS THE SIGN HAS THE 

; INTEGER VALUE 0 FOR PLUS AND 256 (RATHER THAN 1) 

; FOR MINUS. 

; BINARY-DECIMAL CONVERSION: The next routines convert 
between a canonical decimal format and the binary format 
specified. The decimal format is defined in Pascal as 


CONST 
SIGDIGLEN = 20; 
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TYPE 
SigDig = string [SIGDIGLEN]; 
Decimal = record 
sgn : 0.61; 
exp : integer; 
sig : SigDig 
end; 


3; byte of the allotted word, so the two legal word values 
; of sgn are O and 256. 


a ee me a es a ee ee ee ee ee ee ee ae ee ee ee 


a 
> 
3; Note that Lisa Pascal stores the sgn in the high-order 
> 
> 


ce ec a ee a se ee ee a ee ee ne a a ee ee ee a a ee ee a a ee ee ee 


Decimal to binary conversion is governed by a format 
record defined in Pascal as: 


TYPE 
DecForm = record 
style : (FloatDecimal, FixedDecimal); 
digits : integer 
end; 


we we we we we we we we wo 


Note again that the style field is stored in the high- 
order byte of the allotted word. 


These are the only operations with three operands. The 
pointer to the format record is deepest in the stack, 
then the source pointer, and finally the destination 

3; pointer. 

«MACRO FDEC2X 

MOVE.W #FFEXT+FOD2B,-(SP) 

JSRFP 

- ENDM 


we we we we we we 


»MACRO FDEC2D 

MOVE.W #FFDBL+FOD2B,-(SP) 
JSRFP 

- ENDM 


«MACRO FDEC2S 

MOVE.W #FFSGL+FOD2B,-(SP) 
JSRFP 

- ENDM 


«MACRO FDEC2C 
MOVE.W #FFCOMP+FOD2B,-(SP) 


JSRFP 
« ENDM 
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; Binary to decimal conversion. 


eMACRO FX2DEC 

MOVE.W #FFEXT+FOB2D,-(SP) 
JSRFP 

e ENDM 


eMACRO FD2DEC 

MOVE.W #FFDBL+FOB2D,-(SP) 
JSRFP 

e ENDM 


+MACRO FS2DEC 

MOVE.W #FFSGL+FOB2D,-(SP) 
JSRFP 

e ENDM 


»MACRO FC2DEC 
MOVE.W #FFCOMP+FOB2D,-(SP) 


JSRFP 
-ENDM 


ee Se ES A eS SE A Se oe ee 


FOLNX e EQU $0000 
FOLOG2X -EQU $0002 
FOLNIX - EQU $0004 
FOLOG21X -EQU $0006 
FOEXPX - EQU $0008 
FOEXP2X -EQU $SOO00A 
FOEXP1X - EQU $000C 
FOEXP21X -EQU $O0O0E 
FOXPWRI - EQU $8010 
FOXPWRY -EQU $8012 
FOCOMPOUNDX - EQU $c014 
FOANNULTYX -EQU $c016 
FOSINX -EQU $0018 
FOCOSX -EQU SOOLA 
FOTANX -EQU $OO1C 
FOATANX »EQU SOOLE 
FORANDOMX -EQU $0020 


eMACRO FLNX 

MOVE.W #FOLNX,-(SP) 
JSRELEMS 

-ENDM 


«MACRO FLOG2X 
MOVE.W #FOLOG2X,-(SP) 
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JSRELEMS 
- ENDM 


»MACRO FLN1X 

MOVE.W #FOLNIX,-(SP) 
JSRELEMS 

«ENDM 


»MACRO FLOG21X 

MOVE.W #FOLOG21X,-(SP) 
JSRELEMS 

-ENDM 


-MACRO FEXPX 

MOVE.W #FOEXPX,-(SP) 
JSRELEMS 

. ENDM 


«MACRO FEXP2X 

MOVE.W #FOEXP2X,-(SP) 
JSRELEMS 

- ENDM 


»MACRO FEXP1X 

MOVE.W #FOEXP1X,-(SP) 
JSRELEMS 

- ENDM 


»MACRO FEXP21X 

MOVE.W #FOEXP21X,-(SP) 
JSRELEMS 

- ENDM 


«MACRO FXPWRI 

MOVE.W #FOXPWRI,-(SP) 
JSRELEMS 

. ENDM 


«MACRO FXPWRY 

MOVE.W #FOXPWRY,-(SP) 
JSRELEMS 

- ENDM 


«MACRO FCOMPOUNDX 

MOVE.W #FOCOMPOUNDX,-(SP) 
JSRELEMS 

-ENDM 


»MACRO FANNUITYX 

MOVE.W #FOANNUITYX,-(SP) 
JSRELEMS 

-ENDM 


»MACRO FSINX 
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MOVE.W #FOSINX,-(SP) 
JSRELEMS 
e ENDM 


eMACRO FCOSX 

MOVE.W #FOCOSX,=-(SP) 
JSRELEMS 

e ENDM 


eMACRO FTANX 

MOVE.W #FOTANX,-(SP) 
JSRELEMS 

e ENDM 


eMACRO FATANX 

MOVE.W #FOATANX,-(SP) 
JSRELEMS 

- ENDM 


eMACRO FRANDOMX 

MOVE-W #FORANDOMX,-(SP) 
JSRELEMS 

- ENDM 


ce cr ec ce em a es a a ae ae a cn es a es ae ee ee ee ee re 
a a a ce a ee a en ee re ee ee ee a ee = 
0 eee ao a ee re eo a a ee ee ee ee ee er rr owe = 


ee ee em es MS A A SS a a a a oS A SS SS AS HO SS ED DD OS HS nD eS SS SS Oe 
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Introduction 


FP68K provides conversions between the extended floating-point format and 
three integer formats: 


intl6 -- 16-bit two's complement 
int32 -- 32-bit two's complement 
comp64 -— 64-bit two's complement with the reserved value 


hexadecimal 8000000000000000. 


One Pascal program, ITBATTERY.TEXT, tests all three conversions. This 
document describes how to use and, if necessary, modify the tests. 


Compiling and running 


ITBATTERY.TEXT uses the SANE interface (see the "High Level Interface" 
document, so it must be linked with the SANE object files, as well as with the 
usual nonarithmetic Pascal run-time libraries (e.g. *MPASLIB on Lisa). The 
program will simply run to completion, with a Pascal HALT if an error is 
found; execution time may run to 15 minutes on a Lisa system. 


What is tested 


Each of the integer formats is tested in two phases. First, a collection 
of specific extended numbers is converted to the integer format, with tests 
for correct rounding and signaling of the invalid exception when appropriate. 
Then a set of 


integer --> extended --> integer 
conversions is run, with the input and output integers compared for equality. 
In the case of intl6, all 2°16 cases are run. However exhaustive testing of 


int32 and comp64 is infeasible so a loop is set up to do 2716 tests from 
several starting points. 
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Introduction 


The most important and rigorous set of tests of FP68K is the set of 
so-called IEEE test vectors. These tests, developed by the author while at 
Zilog, are used to test implementations of proposed standard P754. They were 
donated to the IEEE subcommittee 754 by Zilog Inc-, and are now distributed by 
that subcommittee. The tests have undergone major revision within Apple, 
thanks especially to Jim Thomas of PCS. 


Form of the tests 


Each vector is an ascii string describing an operation, operands, and the 
result. For example, "lincl" is the floating-point number (of the format 
under consideration) next larger than 1. When ")" 4s subtracted from "lincl", 
the result is "lulpl", just one unit in the last place of 1. Written this 
way, the vectors may be applied to any floating-point format. The tests 
carefully inspect the nuances of rounding and exception handling. A document 
is under development to explain in detail the next release of the test 
vectors, scheduled for early 1983, after some last details of the standard are 
cleared up- 


Files 


The test vectors are contained in a family of files by the name of 
TVxxxxe2eTEXT and TWxxx.2.TEXT. The "2" refers to version 2 of the tests. 
(Version 1 was based on Draft 8.0 of the standard.) The file TLIST.TEXT is a 
list of the test file names to be used in any given run of the test. Pascal 
file TD68.TEXT with unit TD68FP.TEXT actually run the tests. These interface 
with FP68K exclusively through the SANE interface. 
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Introduction 


Since the binary <--> conversions within FP68K approximate the 
mathematical identity operation, they lend themselves to certain types of 
self-testing. For example, if enough decimal digits are kept, then the 
conversion 


binary --> decimal --> binary 


is the identity mapping when results are rounded to nearest. The number of 
digits required turns out to be 9 for single and 17 for double. A similar 
test performs the first conversion rounding toward plus infinity and the 
second rounding toward minus infinity. In this case the final result may 
differ from the starting value by one unit in the direction of the latter 
rounding, so the program allows this discrepancy. 


This document describes the test files and how they can be run. For 
details of the underlying error analysis (which is quite subtle) see the paper 
“Accurate Yet Economical Binary-Decimal Conversions" by J. Coonen. 


Test programs 


The test programs are: 


10S. TEXT 
IOSF. TEXT 
IOD. TEXT 
IODF. TEXT 
IONAN. TEXT 
IOPSCAN. TEXT 


The letter "S" and "D" distinguishes single and double tests. The 10S.TEXT 
and IO0D.TEXT tests run with both rounding to nearest and the directed 
roundings. The "F" tests use fixed-format output rather than floating-format 
output for the intermediate decimal string. The LOPSCAN test is used to check 
the preformance of the printer and scanner used by SANE68, and included from 
file SAPSCAN.TEXT. The IONAN test checks the input and output conversion of 
some 20 stock NANs, and then allows the user to enter any decimal string to be 
converted to the three formats in three rounding modes. Neither IOPSCAN nor 
IONAN are self-checking; rather, the user must monitor their output. 


The tests cover extreme intervals where the decimal numbers are sparsest 
and densest with respect to the binary numbers. Sparse intervals have the 


form [10*N, 2*n] where the endpoints are nearly equal. Dense intervals have 
the corresponding form [2*m, 107M]. 


Running the tests 


Each of the programs is compiled and run separately. The programs use 
the SANE interface. A test will HALT with a suitable diagnostic if the test 
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fails. 


The single format cases are few enough that their tests can be run 
overnight. However, the double format cases will run essentially forever 
since the number of interesting cases is so great. A few overnight tests 
should be sufficient. 


5 January 83 


Draft 1.2 SANE Binary-Decimal Conversion 3 


Background 


The so-called 1/0 routines for scanning and printing floating-point 
numbers in decimal form are complicated by subtle numerical issues and 
nettlesome design decisions. For example, even the simplest, stripped-down 
conversion routines require over one-third the code space (about 1.3K) of the 
rest of the FP68K binary floating-point package. With a full parser and 
formatter, the conversion routines are much larger. And it is unclear whether 
full routines would be flexible enough for use in different language systems 
and I/O-intensive applications like Visi-Calc. 


Where does the responsibility lie? This note argues that the core 
conversion routines, which are part of the arithmetic package, should be kept 
very simple. Above them -- somewhere in the system -- should be a full 
scanner and formatter available to languages and applications, but not forced 
upon them. This would lead to the most efficient use of code space and 
execution time. 


The Sad Truth 


Numerical I/O can be monstrous. Since each computer language has its own 
grammar for floating-point numbers and its own conventions for output format, 
it almost necessary for each language system on a computer to provide 
significant I/O support. Unfortunately, this may be layered upon the host 
system's 1/0 system. And it is not unusual (Apple III, for example) for a 
language compiler to use different conversion routines than the 1/0 system the 
compiled code utilizes. 


In another case, designers of the UNIX operating system attempted to 
route all conversion through the routines atof(), ascii to floating, and the 
pair ecvt(), fevt() for floating and fixed conversion to ascii. But even this 
fairly clean design has led to VERY complicated software shells around atof, 
ecvt, and fcvt. Numerical accuracy aside, the complexity of just the 
character hacking is forbidding. 


One problem with the UNIX design lies in its failure to properly divide 
responsibility for the distinct processes involved in conversion, namely: 


1. Recognize floating-point strings (in compilers, ...) 

2. Translate strings to numerical values. 

3. Determine which output format (fixed or floating) is 
appropriate for a given value. 

4. Translate a numerical value to a string. 


The utilities atof() and ecvt() provide items 2 and 4. Item 3, printing a 
number in its "nicest" form is provided in rough form through ecvt(). But 
recognizing strings is left to each language compiler's lexical scanner. 
Unfortunately, after a scanner has parsed a floating decimal string, it passes 
it along to atof() where it is parsed once more. 
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A Proposal for Change 


(1) Support, at the arithmetic level, conversions between each of the 
available binary floating-point types and one decimal structure describable in 
Pascal as: 


{* 
** Low-level format of the floating decimal value: 
xk = (-1)*sgn * 10*exp * dig 
** The constant DECSTRLEN is 20 for MAC and 28 for III, since 
** the latter uses very high precision for intermediates. 
*} 
type 
DecStr = string[DECSTRLEN] 
Decimal = record 
sgn: Ocel; {0 for +, 1 for -} 
exp: integer; 
sig: DecStr 
end; 


(2) Rigidly specify the format of Decimal-sig for decimal to binary 
conversions, relying upon a lexical scanner to perform the first parse. The 
decimal value would depend upon the first character of decrec.dig: 


ye hy --> infinity 
"Nxxxeeex'’ ==> NAN, with optional ascii hex digits 0-9, A-F, a-f 
Oy --> zero 


"ddd..ed' <--> string of digits stripped of leading and trailing zeros 


The digit string would never be more than 20 digits long. If present, the 
20-th digit would indicate the absence of nonzero trailing digits beyond the 
20-th (to aid in correct rounding). 


(3) Specify decimal output format through a structure like the Pascal: 


{* 
** Qutput format specifier. 
*} 
type 
DecForm = record 
style: (float, fixed); 
digits: integer 
end; 


For "float" conversions, digits is the number of significant digits to be 

delivered in Decimal.sig. For "fixed" conversions, count is the number of 
fraction digits to be converted (a negative count suppresses conversion of 
low-order integer digits). 


Sometimes it is desired to print a number in the nicest form possible for 


a given field width. For example, the string "1.23456789" conveys much more 
information in 10 characters than does "1.2345e+04". Such conversions are 
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discussed in the next section. 


(4) Provide a scanner and formatter which, if not of most general use, 
provide models that can be tailored to a particular application. Samples are 
built into the implementation section of the SANE Pascal interface; they are 
contained in the file SAPSCAN.TEXT. 


Binary --> Decimal 
The family of routines: 


S2Dec 
D2Dec 
X2Dec 
C2Dec 


provide conversions to the Decimal record format described above. Special 
cases are keyed by the first character of Decimal.sig: 


'O' : zero 

'I' : infinity 

"'N' : not-a-number, followed by optional ascii hex digits; if there are 
fewer than four, they are padded on the left with 0's. 

'2' : overflow of fixed-style format 


These must be used with a formatter to produce output strings. 
The family: 


S2Str 
D2Str 
X2Str 
C2Str 
uses the built-in formatter, Dec2Str, to generate ascii string output. 


Decimal --> Binary 


These conversions are povided by the complementary set of procedures: 
Dec2S, Dec2D, Dec2X, Dec2C, and Str2S, Str2D, Str2X, Str2C. In the case of 
the Dec2* conversions, the first character of Decimal.sig indicates special 
cases as noted above for *2Dec conversions. 


Infinity and NAN conversions 


Infinity is printed and read as a string of sign characters, "+++++" or 
W W 


On input, NANs have the general form NAN'xxxx:yyy..-y'. The x's and y's 
should be ascii hex digits: 0-9, A-F, a-f. The string portion following NAN 
may be omitted. The x's are padded on the LEFT with 0's to width 4. The y's 
are padded on the RIGHT with 0's to the width of the NAN's significant bit 
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field. 

On output, NANs will be printed in the same format. Leading x=0 and 
trailing y=0 are omitted, but at least one x is printed. If all y=0, then the 
colon and the y field is dropped. 


Any unrecognizable string is converted to a NAN. 
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Background 


Applications like accounting spreadsheets typically need to display 
floating-point values in decimal form within a field of fixed width. For 
maximum readability, the output should be in integer or fixed-point format if 
possible, with floating-point format as a last resort. The idea is to avoid 
listing small integers in the abominable form 0.100000000000E1 reminiscent of 
computing in the McCarthy era. 


The problem 


Given a binary floating-point number X and an ascii field F, display X in 
the "nicest", most informative way within F. 


A proposal 


1. If X may be displayed in a subfield of F, pad X on the left with blanks. 
2. Display the sign of X only if it is '-'. 


3. If X is an integer and F is wide enough to accommodate X, then display X as 
an integer, without a trailing '.'. 


4. Else if X has nonzero integer and fraction parts and F is wide enough to 
accommodate at least the integer part of F and its trailing '.', then display 
X in the fixed-point form ZZZZ.YYYY with as many fraction digits as F will 
accommodate, up to a maximum of 17 significant digits. 


5. Else if |x| < 1 and F is wide enough that X may be displayed in the form 
0.000002Z2Z2Z with no more Os just to the right of the decimal point than 
digits following those 0s, then display X in that fixed-point form with up to 
17 significant digits. 


6- Finally, if all the above fail, then display X in the floating-point form 
Z.ZZ2Z2ZZEYYY with as many significant digits up to 17 as F will accommodate, 
taking into account the width of the exponent field, including its possible 
signe Display the sign of the exponent field only if it is '-'. 


An implementation 


The above choices depend on detailed knowledge of the magnitude of X. 
For example, in producing floating-point output, it is necessary to know the 
number of spaces that will be occupied by the decimal exponent (with sign, it 
could be 1 to 5) in order to know how many significant digits to which to 
round X- In the worst case, this could mean several calls upon the low-level 
conversion routine until the proper output is finally obtained. 


One easy way to bypass these problems, and keep the fundamental 


conversion routine simple, is perform the binary -> decimal conversion in two 
stages. First convert the binary value X to the SANE decimal form: 
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type 
DecStr = string[DECSTRLEN] ; { length is 20 for MAC } 
Decimal = record 
sgn: integer; {0 for +, nonzero for -} 
exp: integer; {as though decimal is at the right of..-} 
sig: DecStr 
end; 
If the conversion is performed with rounding toward 0, conversion style = 
float, and digit count = 19, and if the inexact exception flag is cleared 
before the conversion, then the 19-digit result may be correctly rounded to 
the desired width after the ultimate output format is determined. Since no 
more than 17 digits will ever be displayed (recall that 17 digits suffice to 
distinguish double format binary numbers), the 19 digits together with the 
inexact exception flag permit correct rounding- 


The second step of the conversion decides, on the basis of the 
intermediate decimal form, which format is appropriate. Then the decimal 
value is rounded (in decimal!) and displayed as desired. Note that this 
scheme has as a happy byproduct the ability to round in the (time-honored?) 
“add half and chop" manner that is unavailable within Apple arithmetic itself. 


23 August 82 


Draft 2 F-P IMPLEMENTATION DETAILS 43 


In the interest of compatibility of the floating-point arithmetic on 
Apples II/III and Mac/(Lisa?), the following GRITTY DETAILS were discussed on 
June 29. This is an update on the decisions made then. 


1. Distinguishing signaling and quiet NANs: use the leading fraction bit, 
O-quiet and l-signaling. 


2. Explicit leading bit of extended NANs and INFs: ignore it, that is decide 
whether NAN or INF on the basis of the fraction bits only. 


3+ Quiet NANs have an 8-bit “indicator field" marked by stars in the following 
extended format hex mask: XXXX XX** XXXX XXXX XXXX. This byte is the low half 
of the leading word of significant bits. The interpretation of the field is 
as given page 70 of Apple III Pascal, volume 2, subject to enhancements. 


4. When two quiet NANs are operands to the operations +, -, *, /, and REM, one 
or the other of the NANs is output. When the indicator fields differ, the NAN 
with the larger indicator field prevails; ties are broken arbitrarily. 


5. True to the standard, the sign of an output NAN is unspecified. 


6. Signaling NANs precipitate the invalid operation exception when they appear 
as operands. 


7. Underflow is tested before rounding. CHANGE: this may change depending on 
P754 deliberations in the late summer of '82 


8. Projective INF follows the same rules of signs as affine INF. The 
ABSOLUTELY ONLY differences between affine and projective modes are: the 
UNORDERED=-ness of projective INF in comparisons with finite numbers, and the 
invalid operation exception that arises from the sum of two projective INFs 
with the same sign. CHANGE: projective mode may be removed from P754 in late 
summer '82. 


9. Treatment of unnormalized extended numbers may differ between systems. 68K 
implementations will normalize all such, as is expected of the Motorola and 
Zilog chips. 6502 implementations may support the ANTIQUE warning mode in 
preliminary releases, though it may never be documented for general 
consumption. 


10. The bottom of the extended exponent range is as in the Motorola and Zilog 
implementations (as opposed to Intel). That is, there is no redundancy 
between the bottom two exponent values. 


11. The exponent bias in extended is hex 3FFF, which is used by Intel, Zilog, 
and Motorola. Motorola may insert a word of garbage between the sign/exp 
fields and the significant bits in order to have a 96-bit data type. 


12. Comparisons return results according to local system convenience. 68K: 
return from the floating-point software with the CPU condition codes set 
appropriately for a conditional branch. 6502: for lack of a rich set of 
conditional branches, let the comparison operation be a family of boolean 
tests like "Is X <= Y?" The difference between the two systems should be 
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hidden well below the high-level language interfaces. 


13. Auxiliary functions: relegate functions like nextafter() to the system 
numerical library rather than putting them in the arithmetic engine. 


14. The data types specified by SANE are intl6é, comp32, comp64, £32, £64, x80. 
68K systems will require int32 as well. 


15. Is the Pascal assignment: X := Y; an arithmetic operation when both X 
and Y are variables of the same floating-point format? Or is a straight byte 
copy sufficient? This is really a language issue -- one left dangling by the 
standard. The arithmetic units, if asked to perform a floating move between 
two floating entities of the same format, will perform a full-blown arithmetic 
operation. This will cause side effects if the floating value is a signaling 
NAN (invalid operation) or a denormalized number (underflow). 


16. Precision control is supported by 6502 and 68K packages, but it is 
available only through assembly language -- it is intended only for SPECIAL 
applications anyway. Precision control implies range control, too- 


17. There is no "integer overflow" exception. 
18. Traps? These are so system-dependent there is no hope for perfect 
consistency. So the issue is left as a local matter for each system.e The 


question relevant to each floating-point engine is: "What information will I 
be required to spew out in case of a trap?" 
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i. Design Philosophy 


The software package FP68K provides binary floating-point arithmetic 
according to the proposed IEEE standard P754. This arithmetic is in turn the 
basis for SANE, standard Apple numeric environment. The goal is software 
compatibility between the various Apple products supporting SANE. 


The arithmetic package is reasonably small and fast. Its interface is 
very simple. And it provides just those operations needed for applications 
software. Although developed specifically for Mac, the package is designed 
for use in Lisa, if desired. 

The following sequence of examples illustrates the SANE philosophy: 


Single operation: X+y¥Y 


P754: Compute as if with unbounded range and precision, 
then coerce to destination format. 


Expression evaluation: Z s= (X + Y)/(U + V); 


SANE: Compute all anonymous intermediate subexpressions 
to extended, then coerce to destination format. 


Loop: S := 0.0; 


VERY SANE: Wise programmer uses extended variable S to 
eliminate spurious over/underflows in the inner 
loop, and to reduce the final rounding error. 
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2. Data Types 


The arithmetic supports the following data types. All are specified in 
SANE except for int32 and decimal. Int32 is included for convenience in 68K 
environments, where 32-bit integers are common. Through the decimal type the 
package provides the basis for the binary<->decimal conversions required by 
languages and the I/O system. 


intl6 -- 16-bit two's-complement integer 

int32 -- 32-bit two's-complement integer 

comp64 -- 64-bit integer, with one reserved operand value 
£32 -- 32-bit single floating-point 

£64 -- 64-bit double floating-point 

x80 -—- 80-bit extended floating-point 


decimal -- ascii digit string with integer sign and exponent 


3. Arithmetic Operations 
These operations apply to floating-point operands: 


+, -, *, /, SQRT, REMAINDER, COMPARE, 
ROUND TO INTEGER, TRUNCATE TO INTEGER, LOGB, SCALB, 
ABSOLUTE VALUE, NEGATE, COPYSIGN, NEXAFTER, CLASS 


Except for COMPARE, each produces a floating-point result. COMPARE sets the 
CPU flag bits according to the two operands. Besides its floating-point 
result, REMAINDER returns the sign and four least significant bits of its 
integer quotient in the CPU flags (a very useful trick for argument reduction 
in the transcendental functions). LOGB replaces a number by is unbiased 
exponent, in floating form; SCALB scales a number by an integer power of 2. 


4. Format Conversions 
intXX <--> extended 
comp64 <--> extended 
floating <--> floating (one operand must be extended) 
decimal <--> extended 


5- Internal Architecture 


The package provides 2-address memory to memory arithmetic operations of 
the form 


<op> DST -—> DST and 
SRC <op> DST --> DST 


where DST and SRC are the destination and source operands, respectively. The 
DST operand is always in the extended format. The conversions have the form: 
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SRC --> DST 


where at least one of SRC and DST is a floating-point format. The package 
also provides a few support functions in connection with the floating-point 
error flags and modes. 


Extended format results may be coerced to the PRECISION and RANGE of the 
single or double formats, on an instruction by instruction basis. Then 
subsequent operations are able to take advantage of the trailing zeros to 
improve performance. This feature is provided to expedite special-purpose 
applications such as graphics and is not intended for general usee Only under 
certain circumstances will it actually obtain a speed advantage, rather than a 
DISADVANTAGE, since the package is built to do extended arithmetic. 


6. External Access 


The package is re-entrant, position-independent code, which may be shared 
in multi-process environments. It is accessed through one entry point, 
labeled FP68K. Each user process has a static state area consisting of one 
word of mode bits and error flags, and a two-word halt vector. The package 
allows for different access to the state word in one-process (Mac) and 
multi-process (Lisa) environments. 


The package preserves all CPU registers across invokations, except that 
REMAINDER modifies DO. It modifies the CPU condition flags. Except for 
binary-decimal conversions, it uses little more stack area than is required to 
save the sixteen 32-bit CPU registers. Since the binary-decimal conversions 
themselves call the package (to perform multiplies and divides), they use 
about twice the space of the regular operations. 


7. Calling Sequence 


A typical invokation of the package will consist of a sequence of four 
68K assembly instructions: 


PEA <source address> ;"Push Effective Address" 
PEA <destination address> ;"Push Effective Address" 
MOVE.W <opword>, -(SP) ;"Push" operation word 
JSR FP68K 3;"Call" the package 


(If FP68K resides in system memory, the JSR may be replaced by an A-line trap 
opcode.) Other calls will have more or fewer operand addresses to push onto 
the stack. The opword is the logical OR of two fields, given here in 
hexadecimal: 


"non-extended" operand format, bits 3800: 


0000 -- x80 
0800 -- £64 
1000 -- £32 


1800 -- ILLEGAL 
2000 -- inti6 
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2800 -—- int32 
3000 -- comp64 
3800 -- ILLEGAL 


arithmetic operation code, bits OOILF: 


0000 -- add 

0002 -- subtract 

0004 -—- multiply 

0006 -- divide 

0008 -- compare 

QOOA -- compare and signal invalid if UNORDERED 
000C -—- remainder 

OOOE -- floating, intxx, comp64 --> extended convert 
0010 -- extended --> intXX, comp64, floating convert 
0012 -—- square root 

0014 -- round to integer in floating format 
0016 -- truncate to integer in floating format 
0018 -- scale by integer power of 2 

OO1A -- replace by unbiased exponent 

001C -- classify the floating input 

O001E -—- ILLEGAL 

0001 -- put state word 

0003 -- get state word 

0005 -- put halt vector 

0007 -- get halt vector 

0009 -- decimal --> floating convert 

000B -- floating --—> decimal convert 

O0OD -- negate 

OOOF -- absolute value 

0011 -- copy sign 

0013 -- nextafter 

0015 -- set exception 

0017 -- procedure entry protocol 

0019 -- procedure exit protocol 

001B -- test exception 

OO1D and OOIF are ILLEGAL 


8. Comparisons 


In this arithmetic, comparisons require some extra thought. The 
trichotomy rule of the real number system -- that two numbers are related as 
LESS, EQUAL, or GREATER -- is violated by the NANs, which compare UNORDERED 
with everything, even themselves. So it is necessary for floating-point 
comparisons to use the CPU condition codes in a way that seems surprising at 


first blush: 


RELATION 


FLAGS: X NZVC 


EQUAL 
GREATER 
UNORDERED 
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This encoding leads to a very convenient mapping between the "floating-point Ww 
conditional branches" and the CPU conditional branches. In the following 

table, the '?' refers to UNORDERED. The second column gives the name of the 

branch macro that provides the "floating branch" (see the "Assembler Support" 

document )« 


BRANCH CONDITION MACRO NOTATION CPU BRANCH 
= FBEQ BEQ 
< FBLT BCS 
<, = FBLE BLS 
> FBGT BGT 
Pig: FBGE BGE 
aS FBULT BLT 

| 23 <> = FBULE BLE 

| ?,> FBUGT BHI 
Ly 2a = FBUGE BCC 
? (unordered) FBU BVS 
5D (ordered ) FBO BVC 
2, <,; > (not equal) FBNE BNE 
?, = FBUE BEQ / BVS 
<, > FBLG BNE / BVC 

Only in the last two instances, are two branches required. i 


The variant comparison instruction, that signals the invalid operation 
| exception if its operands are UNORDERED, is useful in high-level languages 
since P754 (and SANE) require that certain UNORDERED comparisons be marked 
invalid. 


Further discussion of the language issues of comparisons may be found in 
"Comparisons and Branching" by Jerome Coonen. 


9 Binary—Decimal Conversions 


The package provides conversion functions intended to be used in 
conjunction with scanners and formatters peculiar to the user environment. 
For decimal to binary conversions, the input parameters are: 


address of Pascal decimal structure: 
record 
sgn : 0..1; 
exp : integer; 
sig : string{20] 
end; 


address of target floating variable 
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The format (£32, £64, x80) of the target is given in the opword. For binary 
to decimal conversions, the input paramaters are: 


address of format structure: 
record 
style : (FloatDecimal, FixedDecimal); 
digits: integer 
end; 


address of source floating variable 


address of decimal structure: 
sign 
exponent 
ascii string of significant digits 


The interpretation of the latter format element depends on the style of the 
conversion. For fixed conversions, the digit count gives the number of 
fraction digits desired (which may be negative). For float conversions, the 
digit count gives the number of significant digits desired. 


Free format binary --> decimal conversions, which display numbers in the 
‘nicest" format possible within given field width constraints, are supported 
in software, using the float style of conversion. Nice conversions are handy 
in applications like accounting spreadsheets where tables of numbers are 
displayed. See the "Binary-Decimal Conversion" document for details. The 
SANE interface gives details about the decimal format. 


10. The State Area 


Each user of the package has three words of static floating-point state 
information. All accesses to the state should be made through the four state 
operations. The state consists of: 


modes and flags word: 
8000 -—- unused 


6000 -- rounding direction: 
0000 -=- to nearest 
2000 -- toward +INF 
4000 -- toward -INF 
6000 -- toward zero (chop) 


1FOO -- error flags, from high to low order: 
1000 -- inexact result 
0800 -- division by zero 


0400 -- floating overflow 
0200 -- floating underflow 
0100 -- invalid operation 


0080 -- rounding of last result 


1 November 82 


Draft 1-7 FP68K -- An Overview 52 


0000 -= not rounded up in magnitude 
0080 -- rounded up in magnitude 


0060 -- precision control: 
0000 -- extended 
0020 -—- double 
0040 -- single 
0060 -- ILLEGAL 


OOLF -- halt enables, correspond to error flags 


halt vector: 
32-bit address of alternate exit from package 


1. Halts 


When an error arises for which the corresponding halt is enabled, a trap 
is taken through the vector in the floating-point state area- The halt 
routine is called as a Pascal procedure of the form 


PROCEDURE MyHalt(VAR r: fpRegs; op3, op2, opl: fpPtr; opcode: integer); 


where 
TYPE 
fpRegs = RECORD BEGIN 
FPRCCR, { 68000 CCR register } 
FPRDOHI, { high word of register DO } 
FPRDOLO { low word of register DO } 
END; 
f£pPtr = “Extended 5 { but may be pointer to any type } 


The only way to return to the package from a halt is to initiate a new 
floating-point operation. There is no way to resume execution of the halted 
operation. 


The state-related operations never halt. The binary-decimal conversions 
do not halt, though the individual operations they employ (such as 
multiplication to form 10*N for some integer N) might halt. 


12. Other Pseudo-Machines 


The package is simple and general enough to be the basis for 
pseudo-machines with register architectures like the 68881 or the Z8070 or 
with an evaluation stack like the Intel 8087. What is needed is simply the 
mechanism to compute addresses in the register file or stack (and check for 
internal consistency), and the set of functions required to manipulate that 
isolated data file (e-g- duplicate the top stack element, negate a register). 


13. Arithmetic Abuse 
The package is designed to be as robust as possible but it is not 


bullet-proof, since it is specified to modify the stack. If the user passes 
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illegal addresses, a memory fault may arise when the package attempts to 
access the operands. And if the user passes the wrong number of address 
operands, then in general the stack will be irreparably damaged. Operation is 
undefined if ILLEGAL values are used in the opword parameter. 


14. Size and Performance 


FP68K is about 4000 bytes long. On a 4mhz system it executes the 
simplest arithmetic operations in about 0.4ms and requires just over 1.0Oms for 
a full extended multiply. Divide and square root are longer yet. 


Comparative timings show that, for double format operations, FP68K is 
just faster than the AMD 9512 on Lisa and is about twice twice as fast as the 
Motorola 68341 code. For single format operations, FP68K is about half as 
fast as the Lisa single-only package, which is just slower than the 9512. 


15- Floating-Point at a Glance 
Figure 1 at the end of this document illustrates the basic control of 
flow in the execution of the floating-point package. The figure is followed 


by a list of observations on the behavior of the package, and of IEEE 
arithmetic in general. 
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1. The package has a single entry point. 


2. The package has two exit points, one for normal subroutine returns and one 
for halts through a vector. 


3. Three classes of operations are distinguished: arithmetic operations, 
binary-decimal conversions, and accesses to the state word and halt vector. 


4. The not-a-number symbols, NANs, are detected at the start of each 
operation. Of them, signaling NANs are the most virulent; they always trigger 
the invalid operation exception. Quiet NANs propagate through operations; a 
precedence rule determines which is output if two are input. 


5. Invalid operations always result in a quiet NAN output. In the case of the 
discrete types INT16, INT32, COMP64, the output value is all zero bits except 
for a leading one bit (that is, 100000...). Floating-point NANs contain an 
error code to indicate their origin (such as 01 for square root of a negative 
number ). 


6. When the input operands are unpacked, the special cases 0, FNZ (finite 
nonzero number), and INF (infinity) are detected. This expedites special 
cases such as 

+INF + FNZ --> +INF 


7. When 0 or INF results from a trivial operation like the example above, no 
further processing is required before the value is packed. All nontrivial 
floating-point results are subject to precision and range coercion to assure 
that they fit in the intended destination. 


8. Integer results are subject to coercion to detect overflow. 


9. Floating-point NAN results are coerced by chopping them to the precision of 
the destination, and checking that a legitimate value results. 


10. Comparisons require special care, since they produce no results but rather 


modify the CPU condition-code register. Comparisons, even when NANs are 
involved, must bypass the coercion steps. 
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Introduction 


This is a brief guide to the program FP68K, a software implementation of 
proposed IEEE standard P754 (Draft 10.0) for binary floating-point arithmetic. 
This guide is intended to aid a programmer wishing to understand the workings 
of FP68K. 


The code 


The software is in the assembly language of the Motorola MC68000, 
following the Apple "TLA" syntax of the Lisa assembler. FP68K is 
non-self-modifying, position-independent code. It has no local data area, 
that is it uses dynamically allocated stack area for all of its temporaries. 
FP68K is one large subroutine whose single entry point has the name FP68K. 


The code is separated into the functionally distinct files: 


FPDRIVER.TEXT -- “includes” the other files... 

FPEQUS. TEXT -- defines set of named constants 
FPCONTROL.TEXT -- organizes the flow of control 

FPUNPACK.TEXT -- unpack input operands to intermediate format 


FPADD. TEXT -- add and subtract 

FPMUL. TEXT -- multiply 

FPDIV.TEXT -- divide 

FPREM. TEXT -- remainder 

FPCMP. TEXT —- compare 

FPSQRT. TEXT —- square root 

FPCVT. TEXT -- floating <--> floating,integer conversions 
FPSLOG. TEXT -- logb, scalb, and class appendix functions 
FPNANS. TEXT -- handle "Not A Number" symbols 
FPCOERCE.TEXT -- post-normalize, round, check over/underflow... 
FPPACK. TEXT -- pack result to storage format 

FPODDS. TEX? —- non-arithmetic operations 

FBD28B. TEXT -- decimal --> binary conversion 

FBB2D. TEXT -- binary --> decimal conversion 


FBPTEN. TEXT -- computes 10°N for nonnegative integer N 


As noted, FPDRIVER.TEXT is a short file which simply includes the other files 
between the ".PROC" header and ".END" trailer. 


Assembling FP68K 


Assemble the file FPDRIVER.OBJ to produce the FP68K object file. 


The one system dependency of FP68K is its access of the floating-point 
state area, as discussed in the "System Implementor's Guide". Near the top of 
FPCONTROL.TEXT is the code which pulls the address of the the 3-word state 
area into register AQ. This code will typically require modification when 
FP68K is moved to a new system. The well-marked comment within FPCONTROL.TEXT 
indicates the different access schemes systems might use. If the state area 


1 November 83 


YY 


Draft 1.6 Mac FP Software Program Notes 57 


is to be located using a constant defined in a public "include" file, then 
that file should be included within FPDRIVER.TEXT. See the comment there for 
details. 


Other than its access to the state area, FP68K is intended to 
system-independent and should not be tailored recklessly. 


Control flow 


There are three fundamentally distinct classes of operations performed by 
FP68K: basic arithmetic, binary-decimal conversions, and manipulations of the 
floating-point state area. The last of these, namely reading and writing the 
state word and the halt vector, is trivial and needs no explanation beyond the 
simple code contained in FPODDS. TEXT. 


The basic arithmetic operations are illustrated in the flow chart at the 
end of this note. The chart is marked to distinguish the function of the 
various files listed above. 


The binary-decimal conversions are quite different from the basic 
operations, and are not described by the basic flow chart. The conversions 
might better be thought of as subroutines which have been implemented within 
FP68K as a matter of architectural convenience. The conversions invoke FP68K 
itself to perform various basic operations like multiply and divide. The 
binary-decimal algorithms are described in considerable detail in the attached 
paper "Accurate, Yet Economical Binary-Decimal Conversions" by J. Coonen. 


Exponent calculations 


FP68K manipulates exponents in a way that might seem surprising at first 
glance. The P754 extended format, on which all FP68K arithmetic is based, has 
a l-bit sign, 15-bit exponent, and a 64-bit significand. However, the actual 
exponent range is not 0 to 32767 (biased by 16383) as the 15-bit exponent 
field would suggest. Rather, it is -63 to 32767 because of the presence of 
tiny denormalized numbers; this is "just a little bit" beyond the stated 
15-bit range. (See the attached paper "Underflow and the Denormalized 
Numbers" by J. Coonen for a discussion of tiny values in P754 arithmetic.) 


Because the operations multiply and divide require the addition and 
subtraction, respectively, of operand exponents in forming their intermediate 
results, the implementor typically expects to have one extra exponent bit for 
intermediate calculations. Thus for P754 extended format calculations, there 
is need for "just a little bit" beyond 16 exponent bits. This elusive 17-th 
bit is discussed in yet another attached paper, "Are 17 Exponent Bits Too 
Many?" It is shown there that 16 bits suffice, if care is taken to perform 
some extra tests in the right places. 


On the 68000 it turns out to be convenient to perform exponent 
calculations in the ADDRESS REGISTERS -- with a full 32 bits. The address 
registers provide just the right functionality: add, subtract, and compare. 
And since floating-point arithmetic is computation-intensive on a small data 
set, only a few of the address registers are actually needed for addresses. 
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Finally, 16-bit constants like the exponent bias may be added into the 32-bit 
exponents with a 2-word instruction, since for "address" calculations the 
constant is first sign-extended out to a full 32 bits. 


Bit field encodings 


This section describes the various bit fields used by FP68K. Some of 
them, like the opcode and the state word, are visible to programs invoking 
FP68K. Others, like the rounding and sign bits, are local to FP68K- 


The OPCODE is the last word pushed on the stack before calling FP68K. It 
is composed of the fields: 


3800 -- "non-extended" operand format: 
0000 -—- x80 
0800 -- £64 
1000 -—- £32 


1800 -- ILLEGAL 
2000 -- intl6 
2800 -- int32 
3000 -- comp64 
3800 -- ILLEGAL 


07EO -— must be zero 


OO1F -- operation code: 
0000 -- add 
0002 == subtract 
0004 -- multiply 
0006 -- divide 
0008 -- compare 
000A -— compare (invalid if UNORDERED) 
000C -—— remainder 
OQOOE -— x80, £64, £32, intl6, int32, comp64 --—> x80 
0010 -— x80 -—> x80, fo4, £32, intl6, int32, comp64 
0012 -- square root (in x80) 
0014 -- round to integer (in x80) 
0016 -~ truncate to integer (in x80) 
0018 -- scale by unbiased power of 2 
OOLA -- replace by unbiased exponent 
001C -- classify the floating input 
OO1E -- ILLEGAL 


0001 -- put state word 
0003 -- get state word 
0005 -- put halt vector 
0007 -- get halt vector 


0009 -- decimal --> floating convert 
QO0B -— floating --> decimal convert 
0O0OD -- negate 

QOOF -- absolute value 

0011 -- copy sign 

0013 -- nextafter 
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0015 -- set exception 
0017 -- procedure entry protocol 
0019 -— procedure exit protocol 


001B -- test exception 
OO1D and OOI1F are ILLEGAL 


The STATE word is static data that perseveres across calls to FP68Ke As 
such, it must live in an area outside FP68K, defined by the host system. 
Typically the state word (and the halt vector, which is a 32-bit address) will 
live in the system's "per-process data area", perhaps a fixed location in 
memory or a fixed offset from some reserved address register. Although the 
STATE word is directly available to the programmer, typical access will be 
through an intermediate layer of software (available, say, in a Pascal unit) 
that insulates the programmer from the details of the actual bit encodings. 
The STATE word is composed of the fields: 


8000 -- unused 


6000 -- rounding mode: 
0000 -— to nearest 
2000 -- toward +INF 
4000 -- toward -INF 
6000 -- toward 0 (chop) 


1FOO -- error flags: 
1000 -- inexact result 
0800 -- division by zero 
0400 -- floating overflow 
0200 -- floating underflow 


0100 -- invalid operation 

0080 -- rounding of last result 
0000 -- not rounded up in magnitude 
0080 -- rounded up in magnitude 


0060 -—- precision control: 
0000 -- extended 
0020 -- double 
0040 -— single 
0060 -- ILLEGAL 


OO1F -- exception halt enables: 
(correspond to error flags above) 


After preliminary decoding in FPCONTROL.TEXT, the OPCODE is expanded out 
into the following 16-bit form: 


8000 -- nonzero iff result has single precision and range 
4000 -- nonzero iff result has double precision and range 
3800 -- source operand format: 
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(same encoding as in OPCODE) 


0700 -- destination operand format: Y 
(same encoding as in OPCODE) 


0080 -- nonzero iff destination operand is input 
0040 —- nonzero iff source operand is input 
0020 -- nonzero iff destination operand is output 


OO1E -- operation code: 
(same encoding as in OPCODE but with low bit 0) 


0001 -- nonzero iff two-address operation 


The ROUND BITS, known as "guard", "round", and "sticky" in documentation 
about P754, are kept in a 16-bit word. Roughly speaking, the guard and round 
bits are the two bits beyond the least significant bit of the intermediate 
result, and the sticky bit is the logical Or of all bits thereafter. The 
sticky bit is necessary to implement the rounding modes of P754. The ROUND 
BITS are kept as: 


8000 -- guard bit 

4000 -— round bit 

3F00 -- 6 extra round bits 

OOFF -- sticky bits a, 


The reason for keeping an entire byte of sticky bits lies in the 68000 
instruction set. The archetype operation involving the sticky bit is the 
right-shift. Any time a bit is shifted off the low end of the sticky "byte", 
it must be logically Or-ed back into sticky. This is done with the 68000 
"SCS" instruction, which sets a given byte to all ls if the carry bit is set, 
and clears the byte to 0 otherwise. Typically, a bit is shifted off to the 
right, it is SCS-ed into an auxiliary byte, and that byte is Or-ed into the 
sticky byte. Although this is the typical use of the sticky byte, the 
programmer should not assume that the sticky byte is always either all 0s or 
all ls. Sometimes, such as in the right shift after a carry-out in ADD/SUB, 
the logical Or will be omitted since it is known that if a 1 was shifted out 
of the sticky byte there will necessarily be another 1 left in sticky. 


The operands' SIGNS are kept together in a byte as follows: 


80 -- source operand sign 

40 -- destination operand sign 

20 -- Exclusive Or of the two operands' signs 
1F -- unused, but not necessarily zero 


If there is just one input operand, its sign is in the high order bit. The 

Exclusive Or is computed just once, at the start of every arithmetic 

operation. Not only is it required for many common operations (+, -, *, /, 

REM, CMP), but it is costly in time and space because of the inefficacy of the WW 
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68000 bit instructions, so it is worthwhile to implement the code sequence 
just once. 


The CCR (condition code register) bits of the 68000 are modified by every 
arithmetic operation, though only the compare instructions leave them in a 
well defined state. A CCR word is maintained by FP68K: 


FFEO -- unused, forced to 0 
0010 -—- X = Extend 

0008 -- N = Negative 

0004 -- Z = Zero 

0002 -- V = Overflow 

0001 -- C = Carry 


The compare operations encode their results as follows: 


RELATION FLAGS: X NZVC 
LESS 11001 
EQUAL 00100 
GREATER 00000 
UNORDERED 00010 


See the FP68K programmer's manual for the software applications of the CCR 
field. 


Register usage 


The key to the speed (such as it is) and compactness of FP68K is that its 
entire working data set may be held in the 68000 register file. Immediately 
upon entry, FP68K saves registers DO-D7, AO-A4 on the stack. Then the 
registers are loaded up as the operation proceeds. Several of the registers 
have a meaning that perseveres across nearly the entire instruction. The 
following list gives a rough idea of register usage: 


D7 hi -- CCR word 

D7 lo -- round bits 

D6 hi -- opcode word 

D6 lo -- error byte (hi) and sign byte (lo) 


D5 -- low 32 source (later result) significant bits 
D4 -- high 32 source (later result) Sle nitiennt bits 
D3-DO -- scratch area 


7 -- SP = stack pointer 


A6 -- stack link pointer 

A5 -- Mac globals poionter 

AS -=- source (later result) exponent 

A3 -- destination exponent 

A2 -- low 32 destination significant bits 
Al -- high 32 destination significant bits 
AO -- pointer to 3-word state area 
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Of course, the arithmetic operations may be viewed as transformations of the 
register file. Following this view, a set of register maps are included at 
the end of this note. They are keyed to MILESTONES marked in the source code- 
The maps indicate register dependencies, and as such should aid in any 
modification of FP68K. Some maps simply indicate the state of the register 
file at a given point, and some indicate register use in a routine, such as 
the widely used right-shift procedure RISHIFT. 


For convenience the maps are printed on onion skin paper; a reference 
sheet slips under the map to fill in the register mask. 


Register DO is modified by the REMAINDER operation, in which case a 
partial integer quotient is returned in DO.W. 


Stack usage 


When called, FP68K assumes that the stack has the form: 


ADDRESS 3 -- used for decimal format code only 
ADDRESS 2 -- source pointer, if any 

ADDRESS 1 -- destination pointer 

OPCODE -- one word 

RETURN ADDRESS 


The number of address operands depends on the operation. FP68K then allocates 
3 more stack words: 


COUNT -- number of bytes in original call frame 
HALT ADDRESS 


This frame is used if a halt is taken. The COUNT field allows the halt 
handler to simply pop the original operands and return, if desired. 


Above this frame, FP68K pushes registers DO-7, AO-6. In the progress of 
an operation, up to 6 more words of stack may be used. The total stack usage, 
after the call, is then up to 3 + 32 + 6 = 41 words. The binary-decimal 
conversions may use twice this much since they invoke FP68K to perform basic 
arithmetic operations. 


Conditional assembly 


rm . - . =i ec tease 2 11 . mmr or om _¢ es a 


ye a ge ee ee ee ee ee a ee ee | Ne eee ge eee ee eae ee eS Re ee en eee mee £8 Wwe atte PVSteese LV 
the floating-point state area is loaded into register AO at the start of 
FPCONTROL-TEXT. Since the location of this area is system-dependent, 
conditional assembly is used to locate the field. Of course, this means that 
the effective address of the state area must be known at assembly time. 


Conditional assembly is also used to resolve syntactic inconsistencies 
between various 68000 assembly language formats. The program counter (PC) 
relative addressing modes are heavily used in the implementation of jump 
offset tables within FP68K. A typical use is the instruction sequence: 
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MOVE.W JMPTAB( DO) , DO 
JMP JMPTOP( DO) 


Here JMPTAB is a table of address offsets from the label JMPTOP, and register 
DO contains a word index into JMPTAB. Some assemblers force the programmer to 
write: 


MOVE.W  JMPTAB(PC,DO),DO 
JMP JMPTOP( PC, DO) 


in order to assure PC-relative addressing. However, the Lisa assembler 
PROHIBITS this syntax, although it produces the desired code. An assembly 
flag is used to generate whichever of the two formats is suitable for a given 
compiler. 


Pascal enumerated types 


Lisa Pascal attempts to encode enumerated types in byte fields, which are 
then stored as the high byte of the target word. This affects structures like 
DecForm and Decimal, defined in the Pascal interface (see that document for 
details). Although the most seriously affected programs are the test drivers, 
the affected files in the basic package are FBB2D.TEXT and FBD2B.TEXT. Those 
files contain explicit comments when a byte test is used where an Apple III 
programmer (for example) might expect a word test. 
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MAC—PRINT 


TO: MacPrint Users DATE: November 5, 1983 
SUBECT: The .Print Oriver FROM: Owen Densmore 


has 


Introduction & Installation. eae 


The Print driver lives in the System.rsrc file as ".Print” snd ResiD=2, RefNum=$FFFOD. 
[Also in System-rsre is a string (ResID=$E000, -8192) containing the rile name of the 
Print resource file for the higher level print code. This is currently “ImageWriter". 
There may be more stuff later, too.] 


The driver currently hes two source files: PrOrvr68k and CiDrvr68k which are linked to 
PrDrvr.obj. This is stored in the Print resource file under an alias: .XPrint, id=$ECCo. 
This is done es @ backup for the driver and to allow installation of the driver into 
System.rsrc. Until the installation program is written, we also store the driver, and 
any other System.rsrc printing resources in @ "Stub" resource: PrSys.rsrc. To install 
these into System.rsrc, simply put PrSys.rsre on your Mac disk and use RMover: 

Open PrSys 

Copy PrDrvr, the Str, ... into the scrap 

Close PrSys ; 

Open System.rsrc (without selecting anything!) 

Paste 

Quit 

[..You may have to move journal to some other ID if it is at id 2. Just move to a free orn ia.] 


Driver calls 
The driver contains the following calls: 


Status: Font Mgr dev info call. 


Controls: = 
iPrBitsCtl = 4; ; 
iPrIOCtl =5; 
iPrEvtCtl = 6: 
iFMgrCtl = 3; 


The FMoar control call (8) is the “tail hook” which allows the printer to override the 
font manager's font selection. 


The Print Event Control (6) uses one long param for handling two special Bitmap printing cases: 


es we Se 


Msg Format: Byte 350; Byte 2=$FF for Screen, $FE for Top FOlder; Byte 1 & 0 = Print Criver's Fett. 


CSParam = The Keyt(apj event message generated by special key combinations: 
1IPrévtAll = SOOFFFFFD; 
1PrEvtTop = SOOFEFFFD; 


The FMor control call (8) is the "tail hook" which allows the printer to override the 
font manager's font selection. 


The Printer [0 Control (5) uses three long params for writing raw data to the orinter: 


CSParem = pointer to a byte string 
CSP er am-+4 = @ long count of bytes 
CSParam+8 = pointer to an idle proc; use NIL for none. 


The Bitmap Printing Control (4) uses three long params for printing a portion of a bitmap: 


CSP ara = pointer to QuickDraw bitmap 
[SP ar am+4 = pointer to rectangle within bitmap [local coords] 
CSParam+8 = a control parameter: use 0 for screen printing 


Pace | 


Thus to print the entire screen, use params: screenBits, screenBits.bounds, 0. To print 
the contents of a window, use params: window.port&its, window.portRect, 0. 


PrScreen, some driver glue 
The unit PrScreen [<100 bytes] contains aids to use of the Driver: 


PROCEDURE PrDrvrOpen; aad 
PROCEDURE PrOrvrClose; 
PROCEDURE PrCtiCall (iwhichCtl: Integer; lParsm1, !Param2, iParam2: Longint); 
A generalized Control proc for the Printer driver. 
The main use is for sitmap printing: 
- PrCtlCall (iPrSitsCtl, pBitMap, pPortRect, |Control); 
= 
PROCEDURE PrBits ( pBitMap: Ptr; --QuickDOraw bitmap 
pPortRect: TPRect; --a portrect. use bounds for whole 5itmap 
1Control: Longint ); --O=>Screen resolution/Portrait 
Note PrctiCall (iPrBitsCtl, @MyPort~*.ScreenBits, @MyPort~*.PortRect.Sounds,0} 
performs a screen dump cf just my port's data 


Two special control calls are included in the driver for Screen printing from the 
key board: 

PrctiCail (iPrEvtCtl, IPrEvtAll, 9, 0); Prints the screen 

SrctiCall (iPrEvrCtl, lPrEvtTop, 0, 0); Prints the tcp folder 
These ere handled by the system for key board access but can be called by anyone 
at any time. They can be very cheap printing for ornaments, for example! 


Another useft1 call is used for sending raw data to the printer: 
PrctiCall (PrlOCtl, pBuf, |BufCount, pldleProc); 


These calls are available in two ways. One is simoly to link PrScreen.obj to your program 
and use it as any other unit. See the program "Min" for sampie use. The other way if for 
use by Apes using standard document (heavy!) orinting. They simply call these through 
PrLink as they do for other printing procs. PrScreen is in its own segment, just 35 ar2 cr? 
other printing seaments. 


System dependencies 
The KeyM orcc must be the latest version that Jenerates the printer events. 
The Ram-oased System must be the one that calls the Print driver from the Event catch. 


You need the RMaker that can use negative numoers. 
The Print driver must be installed in System.Rsrc 
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SED 


TO: MacPrint Users DATE: November 7, 1983 
SUBELT: The MacPrint Interface FROM: Owen Densmore 
Introduction 


This is a brief description of the new “Linkless" MacPrint. 


Because MacPrint is is not part of the ROM code it must be included with the Application's 
code. Typically this would be done by including the MacPrint code in your Linker job. 
There are two reasons we don't do this. One is that we want to be able to configure 

new printers without re-linking the new print code into the Applications. The other is 

that we cannot assume that ell OEM's are using the Lisa Workshop's Linker! MicroSoft, 
for example, runs an interpreted “C" environment with @ VAX development system! 


Our solution to this packaging problem is to provide four "PDEF" definition procs ina 
special printing resource file. These four def procs break the printing code into four 
disjoint code segments: Dialogs, Spooling, Draft printing, and Picture printing. In addition, 
there is a driver, “Print”, installed in System.rsrc which is accessed like any other driver 
with Open, Close, Status and Control calls. - 


A new printer is configured by supplying a new printer resource file, and installing its 
file name [ImageWriter, for example] and its .Print driver in System.rsrc. 


Access to these "PDEF" procs is vie a very small (374 byte) piece of Print Glue called 
“PrLink" which must be Linked (or some how included!) into your application. In addition, . 
the .Print driver can be accessed directly. The driver and its use is discussed in detail 

In a seperate document. 


The Psscal interface is "MacPrint.cbj" and the Assembly interface is "Pr&qu.text". There 
are four main groups of procedures: Init/Termination, Dialogs, Spooling/Draft, and Picture 
Printing. This release is our "Seta" release. This means that the interface is as statie 
3S we can make it. No further procedural interface changes will be made. Only changes 
internal to the code will be allowed. 


Initialization 
The Init/Termination code consists of: 


PROCEDURE Prijpen: 

PROCEDURE PrClose; 
These Open/Close the printing code by opening”closing two files: the current print 
resource file [ImageWriter.rsrc, for example] and the Print driver (.Print] which is 
part of the System.rsrc file. 


Dialogs 


The Oislogs maintain the primary printing data structure, the "Print" record. Note ‘rer 
ane of these should be stored in each of your documents so that client use of printing 
can be “remembered”. '/3'll discuss this protocol more later. The dialog procs 3re: 


PROCEDURE PrintOerault ( hPrint: THPrint }; 
This fills a handle to the defaulted Print record from the current print resource fils. 
This does not actually cialog. It is used to initialize new “stationary” and to let 
“listing” style applications to get a valid Print record for printing without dialogs. 
The handle must be ore-allocated as SO bytes. 


PLNCTION PrStlOialog ( Print: THPrint |: Soolean: 
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The Mac Applications provide “visual fidelity”, i.e. “hat you see is what you get". 

This means that you must know something about the printing request sefore it is actually 
made! The PrStiDialog asks for the part of the print request that causes one print job 
to vary from another. For most printers, this is simply the page size snd orientation 
for the document. No guarantee is made that this will always be so, however! The 
guarantee is only that enough information is obtained to fill out the part of the Print 
record called the Prinfo data structure, which will be described further below. 


8) 


FUNCTION PrJobDialog ( Print: THPrint ): Boolean; 
The rest of the Print record is filled out by this dialog. It mainly consists of the 
page range and number of copies. For the Image Writer it also hes the HiRes-LoRes/Oraft ~ 
choice and the type of paper feed. 


The boolean result for both dialogs is the Dolt button: if true, the Client has clicked "OK". 
The Print record should be saved and, for the PrJob, the document spooled and/or printed. 

Note that the initial button settings are derived from the existing Print record values. and 
should be either an old, valid one, or a new, defaulted one. 


Spocling and Draft Printing 


The Spooling/Oraft procs do one of two things: Spool e print file to disk, or provide for an 

Ascii like style of printing. Soth are provided by setting up a graf port and intercepting 
QuickDreaw calls by using our own versions of the QuickDraw bottleneck procs. Thus these embody 
the minimum use of printing by an App: you can either do "Cheap" ascii printing or spool the file 
to be printed later, "offline", by the Printer Application that will read and print the file. 

The interface is via four procs that “bracket’ calls to QuickDraw: 


FUNCTION PrOpenDoc ( hPrint: ‘ THPrint: 
, pPrPort : TPPrPort ; 
pl08uf : Ptr ): TPPrPort: 


Initialize the printing code for this document. The hPrint parameter is a handle «9 3. 

valid Print record. The pPrPort is similar to the Window Manager's Storage parameter: :f 
Non-NIL, I use it, rather than calling NewPtr. The IO Buffer pointer is passed allong to a 
the OS: if NIL, it uses the volume buffer, otherwise it uses yours. The returned pcinter ‘ 
is to the initialized Print "Port" which is simply a GrafPtr, its associated bottleneck 
procs, and a few extra longs for me. The code will initialize for Oraft printing or for 
Pic file spooling by looking at the fOraft fleg in the hPrint data. If the hPrint hes 3 
noen-NIL I[dleProc, it will be called by the draft printing proc. 


PROCEDURE PriloseDoc ( pPrPort: TPPrPort }: 
Puts the above stuff to coed: Flushes the Pic file directories or closes the orint drier 
for draft printing. 


C) 


PROCEDURE ProperPage ( pPrPort: TPPrPort; pPageFrame: TPRect ); 
Initializes the next page. The page frame rectangle is for wizards: set it to NIL. 


PROCEDURE PrClosePage{ pPrPort: TPPrPort ); 
Cleans up the Pic file data structures or ejects the current cage. 


See PrTest for sample usage: 
otyPort := PrOpendoc ( Print, pMyPort, plC8uf }: 


FOR iPage := 1 70 iPages CO SEGIN { ..or WHILE NOT EOF(myOoc} 00 BEGIN . 
PropenPage ( pMyPort, NIL 
{ Hera you image the current sage by calling QuickDraw! The drawing proc 
will need the page size and printer resolution stored in the Print Prints. j 
OrmyPage (iPage, hPrint** Prinfa); 
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PrClosePage [pMyPort)- 
END; 


PrtloseDoc (pityPort) ; 
Picture Printing 


The Pic printing procs are the standard way to print. & third proc is provided to 
do simple bitmap printing. 


PROCEDURE PrPicFile{ hPrint: THPrint ; 
pPrPort : TPPrPort ; 
plOBuf : Ptr; 
pOeveuf : Ptr; 


VAR PrStatus: TPrStatus }; 
This reads and prints the spooled print file. If an IdleProc is included in the Print 
record,-it is-run both during imaging and writing to the serial port. The first three 
parameters are identical to the PrOpenDoc parameters. The device buffer is the “bana” 
buffer and associated data. If NIL, I allocate it. Its size is Print.Prxinfo.idevBytes. 
The status record simply records the progress of printing and may be used by the IdleProc. 
See PrApp for its use. 


PROCEDURE PrPic ( hPic: PicHandle; 
hPrint: TrPrint ; 
pPrPort: TPPrPort ; 
pOevéuf : Ptr; 


VAR PrStatus: TPrstatus )- 
Simply prints from your picture rather than the spooled file. 


PROCEDURE PretiCall (iWhichCtl: Integer; lPerem1, lParem2, lParsm3: Lonalnt)- 
.-1$8 @.genersl control call to the Print driver. In particular: 


PROCEDURE PriotlCall ( iPrBitsCtl{= 4} —The bitmap printing csatrei 
pBitMap: Ptr; —QuickOraw bitmap 
pPortRect: TPRect: —«e portrect. use bouris Pir -ils 


lControl: LongInt ); —0O=>Screen resolution. =:r-~::- 
..dumps a bitmap to the printer. lControl is a device dep param: use O for screer 
printing. Thus SrCtiCall (iPrBitsCtl, @MyPort~.ScreenGits, aMyPort*.PortRect.2curc: | 
performs a screen dump of just my port’s dats 


Notes 


Errors: The alert reader will have noticed a lack of error returns from printing. “a 
‘ve Can issue our own Alerts, we do so. Other errors are handled by cc:-:- pote 
error in the printer globals. The first integer is the current error numr=:. 

In case the user's disk does not have a printing resource file, or it is irccrs:. 
named in System.rsrc, or there is no .Print driver: we simply post an errr =r. 
No-op in the PrLink code. We do not alert from Prtink. 


Size: Printing is really a Mini-Application rather than a library. The code is :.:7:-- 
roughly 8K. Sut this is really a small part of the cost of printing; sven wf oon 
code were "free", the data used by printing can be huge. Current sizes Se 

Code: Print Driver = 780 


Prlink = 374 
Dialogs = 2,226 
Senoling = 1,294 
Orart = 2,134 
Pic Printing = 4,630. 
Cate: Bands = 5K for HiRes 
Picture = 5K to 15K, typically. Max = 32K 
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OLEE 


Bands: 


Spsoling: 


Oreft: 


Prinfo: 


Idle: 


Fonts = 3K to 10K, typically. Max = 32K 

QuickDraw Buf = 2K to 6K, typically; up to 12K for 24 Pt shadow HiRes! 
This is why a separate Printer Application is provided: you may simply spool and let : 
the client use it. For spread sheets, for example, Oraft printing may be adequate 
for mast uses. at 
The size .of a HiRes page bitmap is in the order of 1/4 Megabyte! Printing handles ~ 
this by breaking the page into smaller "bands" and alternates imaging and printing them 
to print a page. For example, a HiRes US Letter size page has 47 bands of 5120 bytes 
for a total of 240,640 bytes. LoRes is 24 bands of 2560 bytes for a total of 51 440. 
[Noté: as resolution doubles, data volume quadruples!] ; 


Even if you plan to try to print from within the App, spooling is useful! It allows 

you to have a very clean swapping stratagy: First you spool, with only 5K of printing 
code and no more than iK data. This may require much of your code and data to be resid: 
But when the data is spooled, you can swapp all of your code and data out and call 
PrPicFile fram its own micro segment! The banding strategy requires very fast imaging 
of the data if it is to ne drawn 50 times per page. This is another reason for spooling: 
Pic drawing is optimal use of QuickDraw! 


Draft printing is & compromise between Ascii/writeLn/Fast printing and QuickDraw. 

One of the strongest Mac attitudes is the full use of the QuickDraw style of imaging. 
Note that there are NO Writein's available for Mac programmers, and NO programs use 2 
command line interface! I decided that the best compromise was Draft printing. It is 
called "Draft" mainly because it “simulates” the output you will get when you print 
‘with standard printing. It is done by simply installing QuickOraw capture procs and 
translating them to the printer's command codes. It thus can provide ful! use of the 
printer's native capabilities, such as bold, underline, fonts, line plotting, etc. _ 
It_also requires no special interface such as WriteLn; thus the standard Apps get if 
without even being aware its happening! ..lts completely under client control! 

“But what do I do if all I want to do is make a Listing?!" Well, its really of so 
sad: simply get a default Print record, and make your own WriteLn! The only res! 
headache is having to be aware of the Page boundaries. Gut the advantage is trat 
the results will nicely fit European paper sizes, and you'll probably find tnsat 

"Bretty Printing’ will be so easy that you'll provide it. Note that it also 

lets you provide Spocled standard printing by simply changing one flag! 


~~ 


The Prinfo record contains the device dependent parameters for the current crivcer. 
If carefully used, it provides the Application with “parametric device indese- iss 22" 
TPrinfo = RECORD 


iDev: Integer; {Font mgr/QuickDraw device code} 
iVRes: Integer; {Resolution of device. in device coordinates, 
ihRes: Integer; { ..note: V before H => compatable with Sore 
- ies Rect; {The page (printable) rectangle in device ccsrc.7 7+: 
NO; 


t 


The most important field is the page rectangle. This gives the current timer or: 
in bits. The next is the nw resolution, in spots oer inch. Finally, there :: 7 - 
QuickDraw - FontMor device number. This lets you get the metrics for 7“ 22 7 2 
fonts, so that you can adjust for screen-printer differences. Correct use 27 ~~ sc: 
will result in a very surprising degree of printer independence. 


The Print record hes a [dleProc: Print.Prlob.eldleProc. it is always returre" 9 _ - 


the default and dialog procs. To use it, simply stuff it with your own arid fics oe 
PrJobODislog and before calling the Oraft or Pic Printing procs. A word > see 
however! The “concurrancy” problems caused by the Idle groc are subtle ara > 

Lock at the PrTest and PrAsp samples for how they do if. The major cris.” 0 “iring 
sure the GrafPort is reset to mine ‘when returning from your idle. Also Clti 7 fiw 
salling Printing procs while idling. They are accessed througn the Proline iinet ct 

is not ra-entrant. The suggested idle proc is one polling for Crnd "." shorts. “> eort 
orinting, simoly out iPrAbort into iPrErr in the PrintVars in low memory. 
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Release: 


Billions of files are released on the Macfrint disk, only four of which you need: 
PrLink to Link with, either MacPrint.obj or PrEqu.text to compile/assemble with, 
the current print resource to run with, and PrApp to let your client print spooled 
files with. New releases of printing simply use a new print resource, even if adding 
a new printer? Note however, that you must have the newest System.rsre file which 
containa two vital printing resources: the Print driver and a string containing the 


“file name of the current printing resource (=ImageWriter]. [f you have an olcer 


System.rsrc, it can be updated with these, using RMover, by pasting the small file 
PrSys.rsre included in the printing release into System.rsrc. 
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TOOLBOX 
NAMES 


File: ToolBox Names 
Report: TrapList 


Selection: Value/Trap: 
through Value/Trap: 


Value/ Name: 


A000 Open 

A001 Close 

AOO2 =Read 

A003 Write 

A004 Control 
A005 Status 

AO06 Kill1iIo 

A007 GetVollInfo 
A008 FileCreate 
A009 FileDelete 
AOOA Openkf 

AOOB Rename 

AOOC GetFileInfo 
AO0D SetFileInfo 
AOOE UnmountVol 
AOOF MountVol 
AO1O FileAllocate 
AO11  GetEOF 

AO12 SetEOF 

A013 FlushVol 
AO14 GetVol 

AO15 SetVol 

A016 FiInitQueue 
AOQ17 Eject 

AO18 GetFPos 

AO19 InitZone 
AOLA GetZone 

AO1B SetZone 

AOIC FreeMen 
AO1D MaxMem 

AOLE NewPtr 

AOLF DisposePtr 
A020 SetPtrSize 
A021 GetPtrSize 
AO22 NWHandle 
A023. DsposeHandle 
A024 SetHandleSize 
AO25 GetHandleSize 
A026 HandleZone 
A027 ReAllocHandle 
A028 RecoverHandle 
A029 HLock 

AO2A HUnlock 

AO2B EmptyHandle 
AO2C InitApplZone 
AO2D SetApplLimit 
AO2E BlockMove 
AO2F PostEvent 


¢ 


equals A000 

equals AFFF 

Fields: 
A030 OSEventAvail 
A031 GetOSEvent 
A032 FlushEvents 
A033 VInstall 
A034 VRemove 
A037 ReadParam 
AO38 WriteParam 
A039 Read DateTime 
AO3A SetDateTime 
AO3B Delay 
AO3C CmpString 
AO3D DrvriInstall 
AO3E DrvrRemove 
AO3F InitUtil 
A040 ResrvMen 
A041 SetFilLock 
A042 = RstFilLock 
A043. - Set FilType 
A044 SetFPos 
A045 FlushFil 
A046 GetTrapAddress 
A047 =SetTrapAddress 
A048 PtrZone 
A049 HPurge 
AO4A HNoPurge 
AO4B SetGrowZone 
AO4C CompactMem 
AOSD PurgeMem 
AO4E AddDrive 
AOSF InstallRDrivers © 
AC50 InitCursor 
AC51 SetCursor 
ACS52 HideCursor 
AC53 ShowCursor 
AC54 UprString 
ACS5 ShieldCursor 
AC56 ObscureCursor 
ACS7 SetApp1 Base 
AC58 BitAnd 
AC59 BitXor 
AC5A BitNot 
ACSB BitOr 
ACSC BitShift 
ACSD BitTst 
AC5E BitSet 
ACSF BitClr 
AC61 Random 
AC62 ForeColor 


AC63 
AC64 
AC65 
AC66 
AC67 
AC68 
AC69 
AC6A 
AC6B 
AC6C 
AC6D 
AC6E 
AC6F 
AC70 
AC71 
AC72 
AC73 
AC74 
AC75 
AC76 


-AC77 


AC78 
AC79 
AC7A 
AC7B 
AC7C 
AC7D 
AC7E 
AC7F 
AC80 
AC81 
AC82 
AC83 
AC84 
Ac85 
AC86 
AC87 
AC88 
AC89 
AC8A 
AC8B 
AC8C 
AC8D 
AC8E 
Ac90 
AC91 
AC92 
AC93 
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a a a ee ee ee ce ce ee a ee eee ae ee oe CO ee 


BackColor 
ColorBit 
Get Pixel 
Stuf fHex 
LongMul 
FixMul 
FixRatio 
HiWord 
LoWord 
FixRound 
InitPort 
InitGraf 
OpenPort 
LocalToGlobal 
GlobalToLocal 
Graf Device 
SetPort 
GetPort 
SetPortBits 
PortSize 
MovePortTo 
SetOrigin 
SetClip 
GetClip 
ClipRect 
BackPat 
ClosePort 
AddPt 

SubPt 

SetPt 
EqualPt 
StdText 
DrawChar 
DrawString 
DrawText 
TextWidth 
TextFont 
TextFace 
TextMode 
TextSize 
GetFontInfo 
StringWidth 
CharWidth 
SpaceExtra 
StdLine 
LineTo 

Line 
MoveTo 


File: 


ToolBox Names 


Report: TrapList 
Selection: Value/Trap: equals A000 

through Value/Trap: equals AFFF 
Value/ Name: 


AC94 
AC96 
AC97 


Moov 

HidePen 
ShowPen 
GetPenState 
SetPenState 
GetPen 
PenSize 
PenMode 
PenPat 
PenNormal 
StdRect 
FrameRect 
PaintRect 
EraseRect 
InvertRect 
FillRect 
EqualRect 
SetRect 
OffsetRect 
InsetRect 
SectRect 
UnionRect 
Pt2Rect 
PtInRect 
EmptyRect 
StdRRect 
Frame RoundRect 
PaintRoundRect 
EraseRoundRect 
InvertRoundRect 
FillRoundRect 
StdOval 
FrameOval 
PaintOval 
EraseOval 
InvertOval 
Fill0Oval 
SlopeFromAngle 
StdArc 
FrameArc 
PaintArc 
EraseArc 
InvertArc 
FillArc 
PtToAngle 
AngleFromSlope 
StdPoly 
FramePoly 


a eer Tire 


PaintPoly 
ErasePoly 
InvertPoly 
FillPoly 
OpenPoly 
ClosePoly 
KillPoly 
OffsetPoly 
PackBits 
UnPackBits 
StdRgn 
FrameRgn 
PaintRgn 
EraseRgn 
InvertRgn 
FillRgn 
NewRgn 
DisposeRgn 
Openkgn 
CloseRgn 
CopyRgn 
SectEmptyRgn 
SetRectRgn 
RectRgn 
OffsetRgn 
InsetRgn 
EmptyRgn 
EqualRgn 
SectRgn 
Unionkgn 
DiffRgn 
XOrRgn 
PeInkgn 
RectInkg 
SetStdProcs 
StdBits 
CopyBits 
StdTxMeasure 
StdGetPic 
ScrollRect 
StdPutPic 
SedComment 
PicComment 
OpenPicture 
ClosePicture 
Kill Picture 
DrawPicture 
ScalePt 


MapPoly 
InitFonts 
GetFontName 
Get FNum 
FMSwapFont 
RealFont 

Set FontLock 
DrawGrowlcon 
DragGrayRgn 
NewString 
SetString 
ShowHide 
CalcVis a 
CalcVisBehind 
ClipAbove 
PaintOne 
PaintBehind 
SaveOld 
DrawNew 
GetWMgrPort 
CheckUpDate 
InitWindows 
NewWindow 
DisposeWindow 
ShowWindow 
HideWindow. 
GetWRefCon 
SetWRefCon 
GetWTitle 
SetWTitle 
MoveWindow 
HiliteWindow 
SizeWindow 
TrackGoAway 
SelectWindow 
BringToFront 
Send Behind 
BeginUpdate 
EndUpdate 
FrontWindow 
DragWindow 
DragTheRgn 
InvalRgn 
InvalRect 
ValidRgn 


File: 


ToolBox Names 


Report: TrapList 
Selection: Value/Trap: equals A000 

through Value/Trap: equals AFFF 
Value/ Name: 


AD2A 
AD2B 
AD2C 
AD2D 
AD2E 
AD2F 
AD30 
AD31 
AD32 
AD33 
AD34 
AD35 
AD36 
AD37 
AD38 
AD39 
AD3A 
AD3B 


—-9i+——-----~- 
ValidRect 
GrowWindow 
FindWindow 
CloseWindow 
SetWindowPic 
GetWindowPic 
InitMenus 
NewMenu 
DisposeMenu 
AppendMenu 
ClearMenuBar 
InsertMenu 
DeleteMenu 
DrawMenuBar 
HiliteMenu 
EnableItem 
DisablelItem 
GetMenuBar 
SetMenuBar 
MenuSelect 
MenuKey 
GetItemIcon 
SetItemIcon 
GetItemStyle 
SetItemStyle 
GetItemMark 
Set ItemMark 
CheckItem 
GetItem 
SetItem 
CalcMenuSize 
GetMHandle 
SetMenuFlash 
PlotIcon 
FlashMenuBar 
Add ResMenu 
PinRect 
DeltaPoint 
CountMItems 
InsertResMenu 
NewControl 
DisposeControl 
KillControls 
ShowControl 
HideControl 
MoveControl 
GetCRefCon 
SetCRefCon 


Fields: 


SizeControl 
HiliteControl 
GetCTitle 
SetCTitle 
GetCtlValue 
GetCtlMin 
GetCt1lMax 
SetCtlValue 
SetCtlMin 
SetCtlMax 
TestControl 
DragControl | 
TrackControl 
DrawControls 
GetCtlAction 
SetCtlAction 
FindControl ' 
DeQueue 
EnQueue 
GetNextEvent 
EventAvail 
GetMouse 
StillDown 
Button 
TickCount 
GetKeys 
WaitMouseUp 
CouldDialog 
FreeDialog 
InitDialogs 
GetNewDialog 
NewDialog 
SetIText 
IsDialogEvent 
DialogSelect 
DrawDialog 
CloseDialog 
DisposeDialog 
Alert 
StopAlert 
NoteAlert 
CautionAlert 
CouldAlert 
FreeAlert 
ParamText 
ErrorSound 
GetDItem 
SetDItem 


cat 
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SetIText 
GetIText 
ModalDialog 
DetachResouce 
SetResPurge 
CurResFile 
InitResources 
RsrcZonelInit 
OpenResFile 
UseResFile 
UpdateResFile 
CloseResFile 
SetResLoad 
CountResources 
Get IndResource 
CountTypes 
GetIndType 
GetResource 
GetNamedResourc 
LoadResource 
ReleaseResource 
HomeResFile 
SizeRsrc 
GetResAttrs 
SetResAttrs 
GetResInfo 
SetResInfo 
ChangedResData 
AddResource 
AddReference 
Rmve Resource 
RmveReference 
ResError 
WriteResource 
CreateResFile 
SystemEvent 
SystemClick 
SystemTask 
SystemMenu 
OpenDeskAcc 
CloseDeskAcc 
GetPattern 
GetCursor 
GetString 
GetIcon 
GetPicture 
GetNewWindow 
GetNewControl 


. 


File: ToolBox Names ‘ ‘ Page , 
Report: TrapList Feb 6, 1984 
Selection: Value/Trap: equals A000 ; 

through Value/Trap: equals AFFF 


Value/ Name: Fields: 
ae eee ee See es ee 
ADBF GetMenu ADF4 Exit ToShell Se 
ADCO GetNewMBar ADF5 GetAppParms 
ADC] UniqueID ADF6 GetResFileAttrs 
ADC2 SystemEdit ADF7 SetResFileAttrs 
ADC8 SystemBeep ADF9 InfoScrap 
ADC9 SystemError ADFA  UnloadScrap 
ADCA PutIcon ADFB LoadScrap 
ADCB TeGetText ADFC ZeroScrap 
ADCC TEInit ADFD GetScrap 
ADCD TEDispose ADFE PutScrap 


ADCE Text Box 
ADCF TESetText 
ADDO TECalText 
ADD1 TESetSelect 
ADD2 TENew 

ADD3 TEUpdate 
ADD4 TEClick 
ADDS TECopy 

ADD6 TECut 

ADD7 TEDelete 
ADDS TEActivate 
ADDY TEDeactivate 
ADDA  TEldle 

ADDB TEPaste 
ADDC TEKey 

ADDD TEScroll 
ADDE TEInsert 
ADDF TESetJust 
ADEO Munger 

ADE1 Hand ToHand 
ADE2 PtrToXHand 
ADE3 PtrToHand 
ADE4 Hand AndHand 
ADES InitPack 
ADE6 InitMath 


ADE7 PackO 
ADE8 Packl 
ADE9 Pack2 
ADEA Pack3 
ADEB Pack4 
ADEC Pack5 
ADED Pack6 
ADEE Pack? 


ADEF PtrAndHand 
ADFO LoadSeg 
ADFl1 UnLoadSeg 
ADF2 Launch 
ADF3 Chain 


LEMMA ZO Re, 


% 


File: ToolBox Names et : Page 1 
Renort: TrapList . Feb 6, 1984 
~~ § ction: Value/Trap: equals AQO0O ; ; 
‘nrough Value/Trap: equals FFFF 
Name: Value/ Fields: 
AddDrive AO4E CopyRgn ACDC EraseArc ACCO 
AddPt AC7E CouldAlert AD89 EraseOval ACB9 
AddReference ADAC CouldDialog AD79 ErasePoly ACC8 
Add ResMenu AD4D CountMItems ADSO EraseRect ACA3 
AddResource ADAB CountResources AD9C EraseRgn ACD4 
Alert AD85 CountTypes AD9E EraseRoundRect ACB2 
AngleFromSlope ACC4 CreateResFile ADB] ErrorSound AD8C 
AppendMenu AD33 CurResFile AD94 EventAvail AD71 
BackColor AC63 Delay A03B ExitToShell ADF4 
BackPat AC7C DeleteMenu AD36 FileAllocate A010 
BeginUpdate AD22 DeltaPoint AD4F FileCreate A008 
BitAnd AC58 De Queue AD6E FileDelete A009 
BitClr ACSF DetachResouce AD92 FillArc ACC2 
BitNot ACSA DialogSelect AD80. FillOval ACBB 
¥: BitOr ACSB DiffRgn ACE6 FillPoly ACCA 
BitSet ACSE DisableItem AD3A FillRect ACAS 
BitShift ACSC DisposeControl ADS55 FillRgn ACD6 
BitTst ACSD DisposeDialog AD83 FillRoundRect ACB4 
BitXor ACS59 DisposeMenu AD32 FindControl AD6C 
. BlockMove AO2E DisposePtr AOLF FindWindow AD2C 
BringToFront AD20 DisposeRgn ACD9 FInitQueue A016 
P, ‘on AD74 DisposeWindow AD14 FixMul AC68 
fC *c, 4enuSize AD48 DragControl AD67 FixRatio AC69 
CalcVis ADO9 DragGrayRgn ADOS5 FixRound AC6C 
CalcVisBehind ADOA DragTheRgn AD26 FlashMenuBar AD4C 
CautionAlert AD88 DragWindow AD25 FlushEvents A032 
Chain ADF3 DrawChar AC83 FlushFil A045 
ChangedResData ADAA DrawControls AD69 FlushVol A013 
CharWidth AC8D DrawDialog AD8] FMSwapFont ADO] 
CheckItem AD45 DrawGrowlIcon ADO4 ForeColor AC62 
Ke Engh Ze, +4scas CheckUpDate AD11 DrawMenuBar AD37 FrameArc ACBE 
POSE Me ClearMenuBar AD34 DrawNew ADOF FrameOval ACB7 
ClipAbove ADOB DrawPicture ACF6 FramePoly ACC6 
ClipRect AC7B DrawString AC84 FrameRect ACAl 
Close ‘A001 DrawText AC85 FrameRgn ACD2 
CloseDeskAcc ADB7 Drvrinstall A03D FrameRoundRect ACBO 
CloseDialog AD82 DrvrRemove AO3E FreeAlert ~ AD8A 
ClosePicture ACF4 DsposeHandle A023 FreeDialog AD7A 
ClosePoly ACCC Eject A017 FreeMem AO1C 
ClosePort AC7D EmptyHandle A02B FrontWindow AD24 
CloseResFile AD9A EmptyRect ACAE GetAppParms ADF5 
CloseRgn ACDB EmptyRgn ACE2 GetClip AC7A 
CloseWindow AD2D EnablelItem AD39 GetCRefCon ADSA 
CmpString A03C EndUpdate AD23 GetCTitle ADSE 
ColorBit AC64 EnQueue AD6F GetCtlAction AD6A 
CompactMem A04&C EqualPt AC81 GetCt1lMax AD62 
Control A004 EqualRect ACA6 GetCtlMin AD61 
fap C80 its ACEC EqualRgn ACE3 GetCtlValue AD60 


iy 
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File: 


ToolBox Names 
Report: TrapList 


Selection: Value/Trap: equals A000 
through Value/Trap: equals FFFF 


Name: 


GetCursor 
GetDItem 
GetEOF 
GetFileInfo 
Get FNum 
GetFontInfo 
Get FontName 
GetFPos 
GetHandleSize 
GetIcon 

Get IndResource 
GetIndType 
GetItem 
GetItemIcon 
GetItemMark 
GetItemStyle 
GetIText 
GetKeys 
GetMenu 
GetMenuBar 
GetMHandle 
GetMouse 


GetNamedResourc 


GetNewControl 
GetNewDialog 
GetNewMBar 
GetNewWindow 
GetNextEvent 
GetOSEvent 
GetPattern 
GetPen 
GetPenState 
GetPicture 
GetPixel 
GetPort 

Get PtrSize 
GetResAttrs 


GetResFileAttrs 


GetResInfo 
GetResource 
GetScrap 
GetString 
GetTrapAddress 
GetVol 

Get VollInfo 
GetWindowPic 
GetWMgrPort 
GetWRefCon 


Value/ Fields: 


eee ores | 


ADB9 GetWTitle 
AD8D GetZone 

AO] GlobalToLocal 
Aooc GrafDevice 
ADOO GrowWindow 
AC8B Hand AndHand 
ACFF HandleZone 
A018 Hand ToHand 
A025 HideControl 
ADBB HideCursor 
ADID HidePen 

ADIF HideWindow 
AD46 HiliteControl 
AD3F HiliteMenu 
AD43 HiliteWindow 
AD41 HiWord 

AD90 HLock 

AD76 HNoPurge 
ADBF HomeResFile 
AD3B HPurge 

AD49 HUnlock 

AD72 InfoScrap 
ADA] InitApplZone 
ADBE InitCursor 
AD7C InitDialogs 
ADCO InitFonts 
ADBD InitGraf 

AD70 InitMath 
A031 InitMenus 
ADB8 InitPack 
AC9A InitPort 

AC98 InitResources 
ADBC InitUtil 

AC65 InitWindows 
AC74 InitZone 

A021 InsertMenu 
ADA6 InsertResMenu 
ADF6 InsetRect 
ADAB InsetRgn 
ADAO InstallRDrivers 
ADFD InvalRect 
ADBA InvalRgn 
A046 InvertArc 
A014 InvertOval 
A007 InvertPoly 
AD2F InvertRect 
AD10 InvertRgn 
AD17 InvertRoundRect 


AD35 
AD51 
ACA9 
ACEl 
AO4F 
AD28 
AD27 
ACC] 
ACBA 
ACC9 
ACA4 
ACDS 
ACB3 


IsDialogEvent 
KillControls 
Kill110 

Kill Picture 
KillPoly 
Launch 

Line 

LineTo 

Load Resource 
LoadScrap 
LoadSeg 
LocalToGlébal 
LongMul 
LoWord 
MapPoly 
MapPt 
MapRect 
MapRgn 
MaxMem 
MenuKey 
MenuSelect 
ModalDialog 
Moov 
MountVol 
MoveControl 
Move PortTo 
MoveTo 
MoveWindow 
Munger 
NewControl 
NewDialog 
NewMenu 
NewPtr 
NewRgn 
NewString 
NewWindow 
NoteAlert 
NWHandle 
ObscureCursor 
OffsetPoly 
OffsetRect 
OffsetRgn 
Open 
OpenDeskAcc 
OpenPicture 
OpenPoly 
OpenPort 
OpenResFile 


rn nn ne ee ee = ee ee ee 
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ToolBox Names 


Report: TrapList 

sction: Value/Trap: equals A000 

chrough Value/Trap: equals FFFF 
Value/ Fields: 


Name: 


OSEventAvail 
PackO 

Packl 

Pack2 

Pack3 

Pack4 

Pack5 

Pack6 

Pack/7 
PackBits 
PaintArc 
Paint Behind 
PaintOne 
PaintOval 
PaintPoly 
PaintRect 
PaintRgn 
PaintRoundRect 
ParamText 

P- Mode 

'  jormal 
PenPat 
PenSize 
PicComment 
PinRect 
PlotIcon 
PortSize 
PostEvent 
Pt2Rect 
PtInRect 
PeInRgn 
PtrAndHand 
PtrToHand 
PtrToXHand 
PtrZone 
PtToAngle 
PurgeMem 
PutIcon 
PutScrap 
Random 

Read 

Read DateTime 
Read Param 
RealFont 
ReAllocHandle 
y verHandle 


AD0A 
ACDA 
A030 
ADE7 
ADE8 
ADE9 
ADEA 
ADEB 
ADEC 


ReleaseResource 


Rename 
ResError 
ResrvMen 
RBmveReference 
Rmve Resource 
RsrcZonelnit 
Ret FilLock 
SaveOld 
ScalePt 
ScrollRect 
SectRect 
SectRgn 
SelectWindow 
Send Behind 
Set Appl Base 
SetApplLimit 
SetClip 
SetCRefCon 
SetCTitle 
SetCtlAction 
SetCtlMax 
SetCtlMin 
SetCtlValue 
SetCursor 
Set DateTime 
SetDItem 
SetEmptyRgn 
SetEOF 
SetFileInfo 
Set FilLock 
SetFilType 
SetFontLock 
SetFPos 
SetGrowZone 
SetHandleSize 
SetItem 
SetItemIcon 
Set ItemMark 
SetItemStyle 
SetIText 

Set IText 
SetMenuBar 
SetMenuFlash 
SetOrigin 
SetPenState 
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Set Port AC73 
SetPortBits AC75 
SetPt AC80 
SetPtrSize A020 
SetRect ACA7 
SetRectRgn ACDE 
SetResAttrs ADA7 
SetResFileAttrs ADF7 
SetResInfo ADA9 
SetResLoad AD9B 
SetRes Purge AD93 
SetStdProcs ACEA 
SetString ADO7 
SetTrapAddress A047 
SetVol A015 
SetWindowPic AD2E 
SetWRefCon AD18 
SetWTitle ADILA 
Set Zone AO1B 
ShieldCursor ACS5 
ShowControl AD5S7 
ShowCursor AC53 
ShowHide ADO8 
ShowPen AC97 
ShowWindow ADI5 
SizeControl ADSC 
SizeRsrc ADAS 
SizeWindow ADID 
SlopeFromAngle ACBC 
SpaceExtra AC8E 
Status A005 
StdArc ACBD 
StdBits ACEB 
StdComment ACF1 
StdGetPic ACEE 
StdLine AC90 
StdOval ACB6 
StdPoly ACC5 
StdPutPic ACFO 
StdRect ACAO 
StdRgn ACD1 
StdRRect ACAF 
StdText AC82 
StdTxMeasure ACED 
StillDown AD73 
StopAlert AD86 
StringWidth AC8C 
StuffHex AC66 


File: ToolBox Names \ Page , 
Report: TrapList Feb 6, 1984 
(> Selection: Value/Trap: equals A000 
through Value/Trap: equals FFFF 
Name: Value/ Fields: 
SubPt AC7F - ValidRect AD2A 
SystemBeep ADC8 ValidRgn AD29 
SystemClick ADB3 VInstall A033 
SystemEdit ADC2 VRemove A034 
SystemError ADC9 WaitMouseUp AD77 
SystemEvent ADB2 Write A003 
SystemMenu ADBS WriteParam A038 
SystemTask ADB4 WriteResource ADBO 
TEActivate ADD8 XOrRgn ACE7 
TECalText ADDO ZeroScrap ADFC 
TEClick ADD4 
TECopy ADDS 
TECut ADD6 
Peck, gina? iad TEDeactivate ADD9 
Skee Tes «6 TEDelete ADD7 
; pce TEDispose ADCD 
TeGetText ADCB 
TEIdle ADDA 
TEInit ADCC 
TEInsert ADDE 
TEKey ADDC 
>> TENew ADD2 
TEPaste ADDB 
TEScroll ADDD 
TESetJust ADDF 
TESetSelect ADD1 
TESetText ADCF 
TestControl AD66 
TEUpdate ADD3 
o4 Text Box ADCE 
PO EFCSIES = Text Face AC88 
TextFont AC87 
TextMode AC89 
TextSize AC8A 
TextWidth AC86 
TickCount AD75 
TrackControl AD68 
TrackGoAway ADIE 
UnionRect ACAB 
Uni onRgn ACES 
UniqueID ADCl 
UnloadScrap ADFA 
UnLoad Seg ADFI1 
UnmountVol AOOE 
UnPackBits ACDO 
UpdateResFile AD99 
a UprString AC54 


f UseResFile AD98 
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File: ToolBox Names 

Report: TrapList 

Selection: Value/Trap: equals A000 
through Value/Trap: equals AFFF 


Value/ Name: Fields: 

A000 Open = 

AOOL Close - 

A002 Read = 

A003 Write - 

A004 Control - 

A005 Status - 

* A006 KilLIO = 

A007 GetVoLiInfo - 

A008 FileCreate - 

A009 FileDelete - 

AOOA'  OpenRf = 

AOOB Rename = 

AOOC GetFileInfo - 

AOOD SetFileInfo - 

AOOE Unmount VoL - 

AOOF Mount VoL - 

A010 FileAlLlocate - 

AO1L GetEOF - 

AO12 SetEOF - 

A013 FlushVolL - 

A014 GetVol - 

AO15 SetVoL - 

A016 FInitQueue - 

AOQ17 Eject - 

A018 GetFPos - 

A019 InitZone startPtr(id4) LimitPtr(id4) masterCount(id2) growZone(ipc4) 

AOLA GetZone theZone(odA0O) 

AOLB SetZone theZone(idA0) 

AO1C FreeMem BytesFree(odDO) 

AO1D MaxMem MaxBytes(odDO) 

AOLE NewPtr byteCount(idDO) Pointer(odA0O) 

AOLF DisposePtr Pointer(idA0O) 

A020 SetPtrSize Pointer(idAO) Size(idDO) 

A021 GetPtrSize Pointer(idAO) Size(odDO) 

A022 NewHand le BytesNeeded(idDO) Handle(odA0) 

A023 Ds poseHandle Hand le( AO) 
wwf Of. SethaadleSize ~ Handle(A0) Size(DO} 

A025 GetHandleSize Handle(AO) Size(DO) 

A026. . HandleZone .. Handle(AO) HeapPtr(A0) 
A027 ReAlLlLocHand le Handle(AO) Size(DO) 

~“A028 - RecoverHandle Pointer(AQ) Handle(A0) 

A029... HLock. .. Hand le(A0) 

AO2A  HUnlock Hand Le( AO) 

A02B EmptyHandle Hand le( ihdA0O) 

A02C InitApplZone < 

A02D SetAppLLimit epee 

AO2E BlockMove SourcePtr(A0) DestPtr(Al) Count(DO) 

AO2F PostEvent - 


Files ToolBox Names 


Report: TrapList 


Selection: Value/Trap: equals A000 
through Value/Trap: equals AFFF 


Value/ Name: 


A030 OSEventAvail 
A031 GetOSEvent 
A032 FlushEvents 
A033 Vinstall 
A034 VRemove 

A037 ReadParam 
A038 WriteParan 
A039 ReadDateTime 
AO3A SetDateTime 
A0O3B ~=—De Lay 

AO3C CmpString 
A03D Drvrinstall 
AO3E DrvrRemove 
AO3F InituUtil 
A041 SetFilLock 
A042 RstFilLock 
A043 SetFilType 
A044 SetFPos 

A045 FlushFil 
A046 GetTrapAddress 
A047 SetTrapAddress 
A048 PtrZone 

A049 =HPurge 

A044  ~=HNoPurge 
AO4B SetGrowZone 
A04C CompactMem 
AO4D PurgeMem 
AOGE AddDrive 
AO4F InstallDrivers 
AC50 InitCursor 
AC51 SetCursor 
AC52 HideCursor 
AC53 ShowCur sor 
AC54 UprString 
AC55 ShieldCursor 
AC56 ObscureCursor 
AC57 SetApp|LBase 
AC58 BitAnd 

AC59 BitXor 

AC5A BitNot 

ACSB BitOr 

AC5C BitShift 
AC5D BitTst 

AC5E BitSet 

ACSF BitClr 

AC61 Random 

AC62 ForeColor 
AC63 BackColor 


Fields: 


theZone( ihA0O) 
Hand Le( AO) 
Hand le(A0O) 


longl(4) long2(4) 
long1(4) long2(4) 
long(4) 

longl(4) long2(4) 
9 


bytePtr(4) bitNum(4) 
bytePtr(4) binNum(4) 
bytePtr(4) bitNum(4) 
color(4) 
color(4) 
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File: 


ToolBox Names 


Report: TrapList 


Selection: Value/Trap: 
through Value/Trap: 


Value/ Name: 


ColorBit 
GetPixel 
Stuf fHex 
LongMul 
FixMul 
FixRatio 
HiWord 
LoWord 
FixRound 
InitPort 
InitGraf 
OpenPort 
LocalToGlobal 
GlobalToLocal 
GrafDevice 
SetPort 
GetPort 
SetPortBits 
PortSize 
MovePort 
SetOrigin 
SetCLlip 
GetClip 
ClipRect 
BackPat 
ClosePort 
AddPt 

SubPt 

SetPt 

Equal Pt 
StdText 
DrawChar 
DrawString 
DrawText 
TextWidth 
TextFont 
TextFace 
TextMode 
TextSize 
GetFontInfo 
StringWidth 
CharWidth 
SpaceExtra 
StdLine 
LineTo 

Line 

MoveTo 
Moove 


Page 3 
July 14 1983 


equals A000 
equals AFFF 
Fields: 
whichBit(2) 

h(2) v(2) 
thingPtr(4) s(2) 
a(4) b(4) dst(4) 
a(4) b(4) 
numerator(2) denominator(2) 
x(4) 

x(4) 

x(4) 
grafpointer(4) 
globalPtr(4) 
grafPointer(4) 
pt(4) 

pt(4) 

device(2) 
grafPtr(4) 
grafPtr(4) 
theBitMap(4) 
width(2) height(2) 
leftGlobal(2) topGlobal(2) 
h(2) v(2) 

rgn(4) 

rgn(4) 

r(4) 

pat(4) 
grafPointer(4) 
source(4) dest(4) 
source(4) dest(4) 
pt(4) h(2) v(2) 
pta(4) ptB(4) 
count(2) textAddr(4) 
ch(2) 

s(4) 

textBuf(4) firstBute(2) byteCount(2) 
textBuf(4) firstByte(2) byteCount(2) 
font(2) 

face(2) 

mode(2) 

size(2) 

info(4) 

s(4) 

ch(2) 

extra(2) 

newPt(4) 

h(2) v(2) 

dh(2) dv(2) 

h(2) v(2) 

dh(2) dv(2) 


File: ToolBox Names 

Report: TrapList 

Selection: Value/Trap: equals A000 
through Value/Trap: equals AFFF 
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Value/ Name: Fields: 

AC96 HidePen = 

AC97 ShowPen = 

AC98 GetPenState pnState(4) 

AC99 SetPenState pnState(4) 

AC9A GetPen pt(4) 

AC9B PenSize width(2) height(2) 

AC9C PenMode mode(2) 

AC9D PenPat pat(4) 

AC9E PenNormal = 

ACAO StdRect verb GrafVerb ; r : Rect 

ACAL FrameRect rs Rect 

ACA2  PaintRect re Rect 

ACA3 EraseRect r: Rect 

ACA4 InvertRect r: Rect 

ACA5 FillRect r: Rect; pat: Pattern 

ACA6 EqualRect - 

ACA7 SetRect VAR r: Rect; left, top, right, bottom: Integer 
ACA8 OffsetRect VAR rs: Rect; dh, dvs: Integer 

ACA9 InsetRect VAR r: Rect; dh, dv: Integer 

ACAA SectRect srcl, src2: Rect; VAR dst: Rect 

ACAB UnionRect srcl, src2: Rect; VAR dst: Rect 

ACAC Pt 2Rect ptl, pt2: Point: VAR dst: Rect 

ACAD PtInRect pt: Point; r: Rect 

ACAE EmptyRect = 

ACAF StdRRect verb : GrafVerb ; r : Rect; ovW, ovH : INTEGER 
ACBO FrameRoundRect r: Rect; ovalWidth, ovalHeight: Integer 

ACBL PaintRoundRect r: Rect; ovalWidth, ovalheight: Integer 

ACB2 EraseRoundRect r: Rect: ovalWidth, ovalheight: Integer 

ACB3 InvertRoundRect r: Rect; ovalWidth, ovalHeight: Integer 

ACB4 FillRoundRect r: Rect; ovalWidth, ovalHeight: Integer; pat: Pattern 
ACB6 StdOval verb : GrafVerb ; r : Rect 

ACB7 FrameOval r: Rect 

ACB8 PaintOval r: Rect 

ACB9  EraseOval r: Rect 

ACBA InvertOval r: Rect 

ACBB Filloval r: Rect; pat: Pattern 

ACBD StdArc verb : GrafVerb ; r : Rect ; startAngle, arcAngle : INTEGER 
ACBE  FrameArc r : Rect; startAngle, arcAngle : INTEGER 

ACBF PaintArc ro: Rect; startAngle, arcAngle : INTEGER 

ACCO EraseArc r : Rect; startAngle, arcAngle INTEGER 

ACC1 InvertArc r : Rect; startAngle, arcAngle INTEGER 

ACC2 = FillArce r : Rect; startAngle, arcAngle : INTEGER; pat : pattern 
ACC3 Pt ToAng le ro: Rect; pt : Point; VAR angle INTEGER 
ACC5 StdPoly verb : GrafVerb ; poly : PolyHandle 

ACC6 FramePoly poly: PolyHandle 

ACC7 PaintPoly poly: PolyHandle 

ACC8 ErasePoly poly: PolyHandle 

ACC9 InvertPoly poly: PolyHandle 
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File: ToolBox Names 

Report: TrapList 

Selection: Value/Trap: equals A000 
through Value/Trap: equals AFFF 

Value/ Name: Fields: 


ACCA FillPoly poly: PolyHandle; pat: Pattern 

ACCB OpenPoly - 

ACCC ClosePoly - 

ACCD  KillPoly poly: PolyHandle 

ACCE OffsetPoly poly: PolyHandle; dh, dv: Integer 
ACCF PackBits - 

ACDO UnPackBits - 

ACDL StdRgn verb : GrafVerb ; rgn : RgnHandle 
ACD2 FrameRgn rgn: RgnHandle 

ACD3 PaintRgn rgn: RgnHandle 

ACD4 = EraseRgn rgn: RgnHandle 

ACD5 InvertRgn rgn: RgnHandle 

ACD6 FillRgn rgn: RgnHandle; pat: Pattern 

ACD8 NewRgn - 

ACD9 DisposeRgn rgn: RgnHandle 

ACDA OpenRgn - 

ACDB CloseRgn rgn: RgnHandle 

ACDC CopyRgn srcRgn, dstRgn: RgnHandle 

ACDD SetEmptyRgn - 

ACDE SetRectRgn rgn: RgnHandle; left, top, right, bottom: Integer; 
ACDF RectRgn rgn : RgnHandle; r : Rect 

ACEO OffsetRgn rgn: RgnHandle; dh, dv: Integer 
ACE1 InsetRgen rgn: RgnHandle; dh, dv: Integer 
ACE2 EmptyRgn rgn: RgnHandle 

ACE3 EqualRgn rgnA rgnB: RgnHandle 

ACE4 SectRgn srcRgnA, srcRgnB, dstRgn: RgnHandle 
ACE5 UnionRgn srcRgnA, srcRgnB, dstRgn: RgnHandle 
ACE6 DiffRgn srcRgnA, srcRgnB, dstRgn: RgnHandle 
ACE7 XOrRgn srcRgnA, srcRgnB, dstRgn: RgnHandle 
ACE8 Pt InRgn pt: Point; rgn: RgnHandle 

ACE9 RectInRgn r:Rect; rgn: RgnHandle 

ACEA SetStdProcs - 

ACEB StdBits VAR scrBits : BitMap; VAR srcRect, dstRect : Rect; mode Inte 
ACEC CopyBits - 

ACED StdTxMeasure - 

ACEE StdGetPic - 

ACEF ScrollRect dstRect: Rect; dh, dv: Integer; updateRgn: rgnHandle 
ACFO StdPut Pic - 

ACF1 StdComment - 

ACF2 PicComment - 

ACF3 OpenPicture picFrame: rect 

ACF4 ClosePicture - 

ACF5 KillPicture pic: picHandle 

ACF6 DrawPicture myPicture: PicHandle; picFrame: Rect 
ACF8 ScalePt = 

ACF9  - MapPt - 

ACFA MapRect - 

ACFB MapRgn - 


File: 


ToolBox Names 


Report: TrapList 
Selection: Value/Trap: equals A000 

through Value/Trap: equals AFFF 
Value/ Name: 


MapPoly 
InitFonts 
GetFontName 
Get FNun 
FMSwapFont 
SetFontLock 
NewString 
SetString 
ShowHide 
CalcVis 
CalcVisBehind 
ClipAbove 
PaintOne 
Paint Behind 
SaveOld 
DrawNew 
GetWMgrPort 
CheckUpDate 
InitWindows 
NewWindow 
DisposeWindow 
ShowWindow 
HideWindow 
GetWRefCon 
SetWRefCon 
GetWTitle 
SetWTitle 
MoveWindow 
HiliteWindow 
SizeWindow 
TrackGoAway 
SelectWindow 
BringToFront 
Send Behind 
BeginUpdate 
EndUpdate 
FrontWindow 
DragWindow 
Drag TheRgn 
InvalRgn 
InvalRect 
ValidRgn 
ValidRect 
GrowWindow 
FindWindow 
CloseWindow 
SetWindowPic 
GetWindowPic 


Fields: 
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fntRec: FontRec; VAR fontError: Integer 


str: 


str40 


sh ; StringHandle; str : Str40 


window: WindowPeek 
startWindow: WindowPeek; clobbered: RgnHandle 


window: 


WindowPeek 


window: WindowPeek; clobbered: RgnHandle 

startWindow: WindowPeek; clobbered: RgnHandle 
window: WindowPeek 
window: WindowPeek; fUpdate: Boolean 


VAR theEvent: 


EventRecord 


boundsRect, title, visible, kind, theProc, behind, refCon 


theWindow: 
theWindow: 
theWindow: 
theWindow: 
theWindow: 
theWindow: 
theWindow: 
theWindow: 
theWindow: 
theWindow: 


theWindow: 
theWindow: 
theWindow: 
theWindow: 


theWindow: 
theWindow: 
badRect 
goodRgen : 
goodRect : 


WindowPtr 
WindowPtr 
WindowPtr 
WindowPtr 
WindowPtr; 
WindowPtr; 
WindowPtr; 
WindowPtr; 
WindowPtr; 
WindowPtr; 


WindowPtr 
WindowPtr 
WindowPtr 
WindowPtr 


WindowPtr; 


WindowPtr; 


: Rect 
RgnHand le 


Rect 


data: Longint 

VAR Title: Str255 

title: Str255 

hGlobal, vGlobal: Integer 
fHiLite: Boolean 


width,height: Integer; fUpdate: Boolean 


startPt: Point 


rgn: RgnHandle 


File: ToolBox Names Page 7 
Report: TrapList July 14 1983 
Selection: Value/Trap: equals A000 

through Value/Trap: equals AFFF 


Value/ Name: Fields: 

AD30 InitMenus - 

AD31 NewMenu menulD : INTEGER; menuTitle : Str255 

AD32 DisposeMenu menu : MenuHandle 

AD33 AppendMenu menu : MenuHandle; data : Str255 

AD34 ClearMenuBar - 

AD35 InsertMenu menu : menuHandle; beforeId: INTEGER; 

AD36 = DeleteMenu menuld: Integer 

AD37. DrawMenuBar - 

AD38 HiliteMenu menuld: Integer 

AD39 EnableItem menu: MenuHandle; item : INTEGER; 

AD3A DisableItem menu: menuHandle; item: INTEGER 

AD3B GetMenuBar - 

AD3C SetMenuBar menuBar : Handle 

AD3D MenuSelect startPt: Point 

AD3E Menukey ch: Char 

AD3F GetItemIcon menu: MenuHandle; item : INTEGER; VAR iconChar : char 
AD40 SetItemIcon menu: MenuHandle; item : Integer; iconChar : Char 


AD41 GetItemStyle menu: MenuHandle; item : INTEGER; VAR styleChar : Char 
AD42 SetItemStyle menu: MenuHandle; item : INTEGER; styleChar : Char 


AD43 Get ItemMark menu: menuHandle; item: INTEGER; VAR markChar: CHAR 
AD44 SetItemMark menu: menuHandle; item: INTEGER; markChar: CHAR 

AD45 CheckItem menu : MenuHandle ; item : INTEGER; checked : Boolean 
AD46 GetItem menu: MenuHandle; item : INTEGER; itemString : Str255 
AD47 SetItem menu : MenuHandle; item : INTEGER; itemString: Str255 
AD48 CalcMenuSize menu: menuHandle 

AD49  GetMHandle menuld: INTEGER 

AD4A SetMenuFlash menu: MenuHandle; flashCount : INTEGER 

AD4B PlotIcon - 

AD4C FlashMenuBar - 

AD4D AddResMenu theMenu: menuHandle; theType: ResType 

AD4E PinRect - 

AD4F DeltaPoint - 

AD50 CountItems - 

AD51L InsertResMenu - 

AD54 NewControl ownWindow: WindowPtr; boundsRect; title; visible; value; min; 


AD55 DisposeControl theControl : ControlHandle 
AD56 KillControls theWindow: windowPtr 


AD57 ShowControl theControl : ControlHandle 

AD58 HideControl theControl : ControlHandle 

AD59 MoveControl theControl : ControlHandle; h,v : INTEGER 

AD5A GetCRefCon theControl : ControlHandle 

AD5B SetCRefCon theControl : ControlHandle; data : LongInt 

AD5C SizeControl theControl : ControlHandle; w, h : INTEGER 

ADS5D HiliteControl theControl : ControlHandle; hiliteState: INTEGER 
AD5E GetCTitle theControl : ControlHandle; VAR title : Str255 
ADSF SetCTitle theControl : ControlHandle; title : Str255 

AD60 GetCValue theControl : ControlHandle 


AD61 GetCtlMin theControl : ControlHandle 
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File: ToolBox Names 
Report: TrapList 
Selection: Value/Trap: equals A000 


through Value/Trap: equals AFFF 
Value/ Name: Fields: 
AD62 GetCtlMax theControl : ControlHandle 
AD63 SetCtLValue theControl : ControlHandle; theValue : INTEGER 
AD64 SetCtLMin theControl : ControlHandle; theValue : INTEGER 
AD65 SetCtilMax theControl : ControlHandle; theValue ;: INTEGER 
AD66 = TestControl theControl : ControlHandle; thePt : Point 
AD67 DragControl theControLl: ControlHandle; startPt: Point; bounds: Rect; axis: 
AD68 TrackControl theControl : ControlHandle; actionProc : ProcPtr 
AD69 DrawControls theWindow : WindowPtr 
AD6A GetCtlAction theControl: ControlHandle 
AD6B SetCtlAction theControl: ControlHandle; actionProc: procPtr 
AD6C FindControl theEvent: EventRecord; VAR theWindow: WindowPtr; VAR theContro 
AD70 GetNextEvent mask: Integer; VAR theEvent: EventRecord 
AD71L = EventAvail mask: Integer; VAR theEvent: EventRecord 
AD72 GetMouse VAR pt: Point 
AD73 StillDown = 
AD74 = Button = 
AD75 = TickCount = 
AD76 = GetKeys - 
AD77 WaitMouseUp - 
AD79 = FP68K - 
AD7B InitDialogs - 
AD7C GetNewDialog - 
AD7D NewDialog - 
AD/E SetIText = 
AD7F IsDialogEvent = 
AD80 DialogSelect - 
AD81 DrawDialog - 
AD82 CloseDialog - 
AD83 DisposeDialog = 
AD85 Alert = 
AD86 =StopAlert alertNo : Integer 
AD87 NoteAlert alertNo : Integer 
AD88 CautionAlert alertNo : Integer 
AD89 CouldAlert alertNo : Integer 
AD8A- FreeAlert alertNo : Integer 
AD8B ParamText citel, cite2, cite3 Str20 
AD8C ErrorSound - 
AD8D GetDItem - 
AD8E SetDItem - 
AD8F SetIText - 
AD90 GetIText - 
AD91 ModalDialog - 
AD92 DetachResouce - 
AD93 SetResPurge - 
AD94 CurResFile - 
AD95 InitResources - 
AD96 RsrceZonelInit - 
AD97 OpenResFile fileName: Str255 


YY 


File: 


ToolBox Names 


Report: TrapList 
Selection: Value/Trap: 

through Value/Trap: 
Value/ Name: 


AD98 
AD99 
AD9A 
AD9B 
AD9IC 
AD9D 
AD9E 
AD9F 
ADAO 
ADA1 
ADA2 
ADA3 
ADA4 
ADA5 
ADA6 
ADA7 
ADA8 
ADA9 
ADAA 
ADAB 
ADAC 
ADAD 
ADAE 
ADAF 
ADBO 
ADB1 
ADB2 
ADB3 
ADB4 
ADB5 
ADB6 
ADB/ 
ADB8 
ADB9 
ADBA 
ADBB 
ADBC 
ADBD 
ADBE 
ADBF 
ADCO 
ADC1L 
ADC2 
ADCc4 
ADC5 
ADC6 
ADC7 
ADC9 


UseResFile 
UpdateResFile 
CloseResFile 
SetResLoad 
CountResources 
GetIndResource 
CountTypes 

Get IndType 
GetResource 
GetNamedResourc 
LoadResource 
ReleaseResource 
BeginSubResourc 
EndSubResource 
GetResAttrs 
SetResAttrs 
GetResInfo 
SetResInfo 
ChangedResData 
AddResource 
AddReference 
RmveResource 
RmveRe ference 
ResError 
WriteResource 
CreateResFile 
SystemEvent 
SystemClick 
SystemTask 
SystemMenu 
OpenDeskAcc 
CloseDeskAcc 
GetPattern 
GetCursor 
GetString 
GetIcon 
GetPicture 
GetNewWindow 
GetNewControl 
GetMenu 
GetNewMBar 
UniqueID 
SystemEdit 
LBin2Dec 
LDec2Bin 
Secs2Date 
Date2Secs 
SystemError 


Page 9 
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equals A000 
equals AFFF 
Fields: 
refnum: INTEGER 
refnum: INTEGER 
refNum : INTEGER 
load: BOOLEAN 
theType: ResType 
theType: ResType; index: INTEGER 
index: INTEGER 
theType: ResType; name: Str255 
theType: ResType; name: Str255 
theResource: Handle 
theResource: Handle 
theResource: Handle 
theResource: Handle 
theResource: Handle; attrs: INTEGER 
theResource: handle; VAR theId: INTEGER; VAR theType: ResType; 
theResource: Handle; theId: INTEGER; name: Str255 
theResource: Handle 
theData: handle; theType: ResType; theID: INTEGER; thename: St 
theResource: handle; theId: INTEGER; name: Str255 
theResource: Handle 
theResource: Handle 


- 
- 


theEvent: EventRecord 
theEvent: EventRecord; theWindow: WindowPtr 


menuResult: LongInt 


File: ToolBox Names Page LO 
Report: TrapList July 14 1983 
Selection: Value/Trap: equals A000 

through Value/Trap: equals AFFF 


Value/ Name: Fields: 
ADCA Put Icon = 
ADCC TEInit = 
ADCD TEDispose = 


ADCE TextBox = 
ADCF TESetText = 
ADDO TECalText = 
ADDL TESetSelect - 
ADD2 TENew - 
ADD3 TEUpdate - 


ADD4  TECLick - 
ADD5 TECopy - 
ADD6 ~~ —- TECut - 
ADD7 TEDelete - 


ADD8 TEActivate = 
ADD9 TEDeactivate = 
ADDA TEIdle = 
ADDB TEPaste - 
ADDC  TEKey - 
ADDD TEScroll = 
ADEO Munger - 
ADE1 Hand ToHand - 


ADE2 PtrToXHand = 
ADE3 PtrToHand ad 
ADES5 InitPack - 


ADE6 InitMath = 
ADE7 PackO - 
ADE8 Packl = 


ADEY Pack2 = 
ADEA Pack3 - 
ADEB Pack4 = 
ADEC Pack5 = 
ADED Pack6 - 


ADEE Pack/7 - 
ADFO Load Seg - 
ADF1 UnLoadSeg - 
ADF2 Launch - 
ADF3 Chain - 
ADF4 ExitToShell - 
ADF5 GetAppParms - 
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: LBox Names 
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Report: TrapList 
Selection: Value/Trap: equals A000 
through Value/Trap: equals AFFF 


Name: Value/ Fields: 1 Nastia § 
AddDrive AOSE - = 

AddPt AC7E source(4) dest(4) 

AddRe ference ADAC theResource: handle; theId: INTEGER; name: Str255 
AddResMenu AD4D theMenu: menuHandle; theType: ResType 
AddResource ADAB theData: handle; theType: ResType; theIlD: INTEGER; thename: St 
Alert AD85 - 

AppendMenu AD33. menu : MenuHandle; data : Str255 

BackColLlor AC63 color(4) 

BackPat AC7C pat(4) 

BeginSubResourc ADA4 theResource: Handle 

BeginUpdate AD22 theWindow: WindowPtr 

BitAnd AC58 longl(4) long2(4) 

BitClr AC5F bytePtr(4) bitNum(4) 

BitNot AC5A long(4) 

BitOr AC5B long1(4) Long2(4) 

BitSet AC5E bytePtr(4) binNum(4) 

BitShift AC5C ? 

BitTst AC5D bytePtr(4) bitNum(4) 

BitXor AC59 long1(4) long2(4) 

BlockMove AO2E SourcePtr(A0O) DestPtr(Al) Count(DO) 
BringToFront AD20 theWindow: WindowPtr 

Button AD74 - 

CalcMenuSize AD48 Menu: menuHandle 

CalcVis ADO9 window: WindowPeek 

CalcVisBehind ADOA startWindow: WindowPeek; clobbered: RgnHandle 
CautionAlert AD88 alertNo : Integer 

Chain ADF 3 - 

ChangedResData ADAA theResource: Handle 

CharWidth AC8D ch(2) 

CheckIten AD45 menu : MenuHandle ; item : INTEGER; checked : Boolean 
CheckUpDate AD1L1 VAR theEvent: EventRecord 

ClearMenuBar AD34 - 

ClipAbove ADOB window: WindowPeek 

ClipRect AC7B r(4) 

Close AOOL - 

CloseDeskAcc ADB7 - 

CloseDialog AD82 - 

ClosePicture ACF4 - 

ClosePoly ACCC - 

ClosePort AC7D grafPointer(4) 

CloseResFile AD9A refNum : INTEGER 

CloseRgn ACDB rgn: RgnHandle 

CloseWindow AD2D - 

CmpString AO3C - 

ColorBit AC64 whichBit(2) 

CompactMen A04C - 

Control A004 - 


CopyBits ACEC - 


File: ToolBox Names 


Page 2 
Report: TrapList July 14 1983 
Selection: Value/Trap: equals A000 : 
through Value/Trap: equals AFFF 
Name: Value/ Fields: WY 
CopyRgn ACDC srcRgn, dstRgn: RgnHandle 
CouldAlert AD89 alertNo : Integer 
CountItems AD50 = 
CountResources AD9C theType: ResType 
CountTypes AD9SE = 
CreateResFile  ADBL = 
CurResFile AD94 - 
Date2Secs ADC7 = 
Delay A03B = 
DeleteMenu AD36 menuld: Integer 
DeltaPoint AD4F = 
DetachResouce AD92 = 
DialogSelect AD80 - 
DiffRgn ACE6 srcRgnA, srcRgnB, dstRgn: RgnHandle 
DisableItem AD3A menu: menuHandle; item: INTEGER 
DisposeControl AD55 theControl : ControlHandle 
DisposeDialog AD83 - 
DisposeMenu AD32 menu : MenuHandle 
DisposePtr AOLF Pointer(idA0O) 
DisposeRgn ACD9 rgn: RgnHandle 
DisposeWindow AD14 theWindow: WindowPtr 
DragControl AD67 theControl: ControlHandle; startPt: Point; bounds: Rect; axis: 
DragTheRgn AD26 - 
DragWindow AD25  theWindow: WindowPtr; startPt: Point WW 
DrawChar AC83 ch(2) 
DrawControls AD69 theWindow : WindowPtr 
DrawDialog AD81 - 
DrawMenuBar AD37 - 
DrawNew ADOF window: WindowPeek; fUpdate: Boolean 
DrawPicture ACF6 myPicture: PicHandle; picFrame: Rect 
DrawString AC84 s(4) 
DrawText AC85 textBuf(4) firstBute(2) byteCount(2) 
Drvrinstall A03D - 
DrvrRemove AO3E - 
Ds poseHandle A023 Hand 1le( AO) 
Eject AOQ17 = 
Empt yHandle AO02B Hand le( ihAO) 
EmptyRect ACAE = 
EmptyRgn ACE2 rgn: RgnHandle 
EnableItem AD39 menu: MenuHandle; item : INTEGER; 
EndSubResource ADA5 - 
EndUpdate AD23  theWindow: WindowPtr 
EqualPt AC81 ptA(4) ptB(4) 
EqualRect ACA6 - 
EqualRgn ACE3 rgnA rgnB: RgnHandle 
EraseArc ACCO r: Rect; startAngle, arcAngle : INTEGER 
EraseOval ACB9 r: Rect 
ErasePoly ACC8 poly: PolyHandle 


File: 


ToolBox Names 
Report: TrapList 


Selection: Value/Trap: 
through Value/Trap: 


Name: 


EraseRect 
EraseRgn 
EraseRoundRect 
ErrorSound 
EventAvail 
ExitToSheLl 
FileAllocate 
FileCreate 
FileDelete 
FillArc 
FillOval 
FillPoly 
FillRect 
FillRgn 
FillRoundRect 
FindControl 
FindWindow 

F InitQueue 
FixMul 
FixRatio 
FixRound 
FlashMenuBar 
FlushEvents 
FlushFil 
FlushVoLl 
FMSwapFont 
ForeColor 
FP68K 
FrameArc 
FrameOval 
FramePoly 
FrameRect 
FrameRgn 


FrameRoundRect 


FreeAlert 
FreeMem 
FrontWindow 
GetAppParms 
GetClip 
GetCRefCon 
GetCTitle 
GetCtLlAction 
GetCt lMax 
GetCtlMin 
GetCursor 
GetCValue 
GetDItem 
GetEOF 


Value/ 
ACA3 
ACD4 
ACB2 
AD8C 
AD71 
ADF4 
A010 
A008 
A009 
ACC2 
ACBB 
ACCA 
ACA5 
ACD6 
ACB4 
AD6C 
AD2C 
A016 
AC68 
AC 69 
AC6C 
AD4C 
A032 
A045 
A013 
ADO1 
AC62 
AD79 
ACBE 
ACB7 
ACC6 
ACAL 
ACD2 
ACBO 
AD8A 
AO1C 
AD24 
ADF 5 
AC7A 
AD5A 
AD5E 
AD6A 
AD62 
AD61 
ADB9 
AD60 
AD8D 
AOLL 
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equals AOOO 

equals AFFF 

Fields: 

r: Rect 

rgn: RgnHandle 

r: Rect: ovalWidth, ovalheight: Integer 
mask: Integer; VAR theEvent: EventRecord 


vr: Rect; startAngle, arcAngle : INTEGER; pat : pattern 

rs Rect; pat: Pattern 

poly: PolyHandle; pat: Pattern 

r: Rect; pat: Pattern 

rgn: RgnHandle; pat: Pattern 

r: Rect; ovalWidth, ovalHeight: Integer; pat: Pattern 
theEvent: EventRecord; VAR theWindow: WindowPtr; VAR theContro 


a(4) b(4) 
numerator(2) denominator(2) 
x(4) 


fntRec: FontRec; VAR fontError: Integer 
color(4) 

r : Rect; startAngle, arcAngle : INTEGER 
r: Rect 

poly: PolyHandle 

r: Rect 

rgn: RgnHandle 

r: Rect; ovalWidth, ovalHeight: Integer 
alertNo : Integer 

BytesFree(odDO) 


rgn(4) 
theControl : ControlHandle 


theControl : ControlHandle; VAR title : Str255 


theControLl: ControlHandle 
theControl : ControlHandle 
theControl : ControlHandle 
theControl : ControlHandle 


File: ToolBox 


Names 


Report: TrapList 
Selection: Value/Trap: 
through Value/Trap: 


Name: 


GetFileInfo 
GetFNum 
GetFontInfo 
GetFontName 
GetFPos 
GetHandleSize 
GetiIcon 
GetIndResource 
GetIndType 
GetItem 
GetiItemIcon 
GetItemMark 
GetItemStyle 
GetIText 
GetKeys 
GetMenu 
GetMenuBar 
GetMHand le 
GetMouse 
GetNamedResourc 
GetNewControl 
GetNewDialog 
GetNewMBar 
GetNewWindow 
GetNextEvent 
GetOSEvent 
GetPattern 
GetPen 
GetPenState 
GetPicture 
GetPixel 
GetPort 
GetPtrSize 
GetResAttrs 
GetResInfo 
GetResource 
GetString 
GetTrapAddress 
GetVol 
GetVoLinfo 
GetWindowPic 
GetWMgrPort 
GetWRefCon 
GetWTitle 
GetZone 
GlobalToLocal 
GrafDevice 
GrowWindow 


Value/ 
AOOC 
ADOO 
AC 8B 
ACFF 
A018 
A025 
ADBB 
AD9D 
AD9OF 
AD46 
AD3F 
AD43 
AD41 
AD90 
AD76 
ADBF 
AD3B 
AD49 
AD72 
ADAL 
ADBE 
AD7C 
ADCO 
ADBD 
AD70 
AO31 
ADB8 
AC9A 
AC98 
ADBC 
AC65 
AC74 
A021 
ADA6 
ADA8 
ADAO 
ADBA 
A046 
A014 
A007 
AD2F 
AD10 
AD17 
AD19 
AOQLA 
AC71 
AC72 
AD2B 
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equals AFFF 
Fields: 


SOS SOS SSSTT TTT SOSSSTPVTSVTSSSSSsSsESTESSOSSSTTVCOSTSFFOSTSSOSTOCFCOSsess ses swe 


info(4) 


Handle(AO) Size(DO) 


theType: ResType; index: INTEGER 

index: INTEGER 

menu: MenuHandle; item : INTEGER; itemString : Str255 
Menu: MenuHandle; item : INTEGER; VAR iconChar : char 
menu: menuHandle; item: INTEGER; VAR markChar: CHAR 
menu: MenuHandle; item : INTEGER; VAR styleChar : Char 
menulId: INTEGER 

VAR pt: Point 

theType: ResType; name: Str255 


mask: Integer; VAR theEvent: EventRecord 
pt(4) 
pnState(4) 


h(2) v(2) 

grafPtr(4) 

Pointer(idAO) Size(odDO) 

theResource: Handle 

theResource: handle; VAR theld: INTEGER; VAR theType: ResType; 
theType: ResType; name: Str255 


theWindow: WindowPtr 

theWindow: WindowPtr; VAR Title: Str255 
the Zone(odA0) 

pt(4) 

device(2) 


File: 


ToolBox Names 
Report: TrapList 


Selection: Value/Trap: 
through Value/Trap: 


Name: 


Hand leZone 
Hand ToHand 
HideControl 
HideCursor 
HidePen 
HideWindow 
HiliteControl 
HiliteMenu 
HiliteWindow 
HiWord 

HLock 

HNo Purge 
HPurge 
HUnlock 
InitApplZone 
InitCursor 
InitDialogs 
InitFonts 
InitGraf 
InitMath 
InitMenus 
InitPack 
InitPort 
InitResources 
InitUtil 
InitWindows 
InitZone 
InsertMenu 
InsertResMenu 
InsetRect 
InsetRgn 
InstaliDrivers 
InvalRect 
InvalRgn 
InvertArc 
InvertOval 
InvertPoly 
InvertRect 
InvertRgn 


InvertRoundRect 


IsDialogEvent 
KillControls 
KilLIO 
KillPicture 
KillPoly 
Launch 
LBin2Dec 
LDec2Bin 


Va lue/ 
A026 
ADE1 
AD58 
AC52 
AC96 
AD16 
AD5D 
AD38 
AD1C 
AC6A 
A029 
AQ4A 
A049 
AO2A 
AO2C 
AC50 
AD7B 
ACFE 
AC6E 
ADE6 
AD30 
ADE5 
AC 6D 
AD95 
AO3F 
AD12 
A019 
AD35 
AD51 
ACA9 
ACE1L 
AO4F 
AD28 
AD27 
ACC1 
ACBA 
ACC9 
ACA4 
ACD5 
ACB3 
AD7F 
AD56 
A006 
ACF5 
ACCD 
ADF 2 
ADC4 
ADC5 
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equals AOOO 
equals AFFF 


Fields: 
Handle(AO) HeapPtr(A0) 


theControl : ControlHandle 


theWindow: WindowPtr 

theControl : ControlHandle; hiliteState: INTEGER 
menuld: Integer 

theWindow: WindowPtr; fHiLite: Boolean 

x(4) 

Hand le( AO) 

Hand 1le( AO) 

Hand Le( AO) 

Hand Le( AO) 


globalPtr(4) 

grafpointer(4) 

startPtr(id4) LimitPtr(id4) masterCount(id2) growZone(ipc4) 
menu : menuHandle; beforeId: INTEGER; 
VAR r: Rect; dh, dv: Integer 

rgn: RgnHandle; dh, dv: Integer 

badRect : Rect 

theWindow: WindowPtr; rgn: RgnHandle 

r : Rect; startAngle, arcAngle : INTEGER 
r: Rect 

poly: PolyHandle 

rs Rect 

rgn: RgnHandle 

r: Rect; ovalWidth, ovalHeight: Integer 


theWindow: windowPtr 
pic: picHandle 
poly: PolyHandle 
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Report: TrapList July 14 1983 
Selection: Value/Trap: equals A000 

through Value/Trap: equals AFFF 


Name: Value/ Fields: 

Line AC92 dh(2) dv(2) 

LineTo ACYL h(2) v(2) 

LoadResource ADA2 theResource: Handle 

LoadSeg ADFO = 

Local ToGlobal AC70 pt(4) 

LongMul AC67 a(4) b(4) dst(4) 

LoWord AC6B x(4) 

MapPoly ACFC = 

MapPt ACF9 = 

MapRect ACFA = 

MapRgn ACFB = 

MaxMem AO1LD MaxBytes(odDO) 

Menukey AD3E ch: Char 

MenuSelect AD3D startPt: Point 

ModalDialog AD91 - 

Moove AC94 dh(2) dv(2) 

MountVol AOOF - 

MoveControl AD59 theControl : ControlHandle; h,v : INTEGER 
MovePort AC77 leftGlobal(2) topGlobal(2) 

MoveTo AC93 h(2) v(2) 

MoveWindow AD1B theWindow: WindowPtr; hGlobal, vGlobal: Integer 
Munger ADEO - 

NewControl AD54 ownWindow: WindowPtr; boundsRect; title; visible; value; min; 
NewDialog AD7D = 

NewHandle A022 BytesNeeded( idDO) Hand le(odA0O) 
NewMenu AD31 menuID : INTEGER; menuTitle : Str255 
NewPtr AOLE byteCount(idDO) Pointer(odA0) 

NewRgn ACD8 - 

NewString ADO6 str: Str40 

NewWindow AD1L3 boundsRect, title, visible, kind, theProc, behind, refCon 
NoteAlert AD87 alertNo : Integer 

ObscureCursor AC56 = 

OffsetPoly ACCE poly: PolyHandle; dh, dv: Integer 
OffsetRect ACA8 VAR r: Rect; dh, dv: Integer 
OffsetRgn ACEO rgn: RgnHandle; dh, dv: Integer 

Open A000 - 

OpenDeskAcc ADB6 - 

OpenPicture ACF3 picFrame: rect 

OpenPoly ACCB - 

OpenPort AC6F grafPointer(4) 

OpenResFile AD97 fileName: Str255 

OpenRf AOOA - 

OpenRgn ACDA = 

OSEventaAvail A030 - 

PackO ADE7 - 

Packl ADE8 - 

Pack2 ADE9 = 


Pack3 ADEA - 


File: ToolBox 


Names 


Report: TrapList _ 


Selection: Value 
through Value 
Name: 
Pack4 
Pack5 
Pack6 
Pack7 
PackBits 
PaintArc 
PaintBehind 
PaintOne 
PaintOval 
PaintPoly 
PaintRect 
PaintRgn 
PaintRoundRect 
ParamText 
PenMode 
PenNormal 
PenPat 
PenSize 
PicComment 
PinRect 
PlotIcon 
PortSize 
PostEvent 
Pt2Rect 
Pt InRect 
Pt InRgn 
PtrToHand 
Ptr ToXHand 
PtrZone 
PtToAngle 
PurgeMen 
Put Icon 
Random 
Read 
ReadDateTime 
ReadParam 
ReAllocHandle 
RecoverHand Le 
RectInRgn 
RectRgn 
ReleaseResource 
Rename 
ResError 
RmveReference 
RmveResource 
RsrcZonelInit 
RstFilLock 
SaveOld 


/Trap: 
/Trap: 
Value/ 
ADEB 
ADEC 
ADED 
ADEE 
ACCF 
ACBF 
ADOD 
ADOC 
ACB8 
ACC7 
ACA2 
ACD3 
ACB1 
AD8B 
AC9C 
AC9E 
AC9D 
AC9B 
ACF2 
AD4E 
AD4B 
AC76 
AO2F 
ACAC 
ACAD 
ACE8 
ADE3 
ADE2 
A048 
ACC3 
A04D 
ADCA 
AC61 
A002 
A039 
A037 
A027 
A028 
ACE9 
ACDF 
ADA3 
AOOB 
ADAF 
ADAE 
ADAD 
AD96 
A042 
ADOE 
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equals A000 
equals AFFF 
Fields: 


r : Rect; startAngle, arcAngle : INTEGER 
startWindow: WindowPeek; clobbered: RgnHandle 
window: WindowPeek; clobbered: RgnHandle 
rs Rect 

poly: PolyHandle 

r: Rect 

rgn: RgnHandle 

r: Rect; ovalWidth, ovalheight: Integer 
citel, cite2, cite3 : Str20 

mode(2) 

pat(4) 

width(2) height(2) 

width(2) height(2) 

ptl, pt2: Point: VAR dst: Rect 

pt: Point; r: Rect 

pt: Point; rgn: RgnHandle 


the Zone(ihA0) 
ro: Rect; pt : Point; VAR angle : INTEGER 


Handle(AQ) Size(DO) 
Pointer(A0O) Handle(A0) 
r:Rect; rgn: RgnHandle 
rgn : RgnHandle; r : Rect 
theResource: Handle 


theResource: Handle 
theResource: Handle 


window: WindowPeek 


Files 


ToolBox Names 


Report: TrapList 
Selection: Value/Trap: 
through Value/Trap: 


Name: 


SSVCSSSTSeSeoosee 


ScalePt 
ScrollRect 
Secs2Date 
SectRect 
SectRgn 
SelectWindow 
SendBehind 
SetApplBase 
SetAppLLimit 
SetClip 
SetCRefCon 
SetCTitle 
SetCtlAction 
SetCtlMax 
SetCtlMin 
SetCtlValue 
SetCursor 
SetDateTime 
SetDItem 
SetEmptyRgn 
SetEOF 
SetFileInfo 
SetFilLock 
SetFilType 
SetFontLock 
SetFPos 
SetGrowZone 
SetHandleSize 
Setiten 
SetItemIcon 
SetItemMark 
SetItemStyle 
SetIText 
SetIText 
SetMenuBar 
SetMenuF Lash 
SetOrigin 
SetPenState 
SetPort 
SetPortBits 
SetPt 
SetPtrSize 
SetRect 
SetRectRgn 
SetResAttrs 
SetResInfo 
SetResLoad 
SetResPurge 


Value/ 
ACF8 
ACEF 
ADC6 
ACAA 
ACE4 
ADIF 
AD21 
AC57 
A02D 
AC79 
AD5B 
AD5F 
AD6B 
AD65 
AD64 
AD63 
AC51 
AO3A 
AD8E 
ACDD 
AO12 
AOOD 
A041 
A043 
ADO3 
A044 
AO4B 
A024 
AD47 
AD40 
AD44 
AD42 
AD7E 
AD8F 
AD3C 
AD4A 
AC78 
AC99 
AC73 
AC75 
AC80 
A020 
ACA7 
ACDE 
ADA7 
ADAS 
ADOB 
AD93 
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Fields: 


dstRect: Rect; dh, dv: Integer; updateRgn: rgnHandle 
srcl, srce2: Rect; VAR dst: Rect 
srcRgnA, srcRgnB, dstRgn: RgnHandle 


theWindow: 


WindowPtr 


rgn(4) 

theControl : ControlHandle; data : LongInt 
theControl : ControlHandle; title : Str255 
theControl: ControlHandle; actionProc: procPtr 


theControl : ControlHandle; theValue : INTEGER 
theControl : ControlHandle; theValue : INTEGER 
theControl : ControlHandle; theValue : INTEGER 


cursor(4) 


Handle(A0O) Size(DO) 

menu : MenuHandle; item : INTEGER; itemString: Str255 
menu: MenuHandle; item : Integer; iconChar : Char 
menu: menuHandle; item: INTEGER; markChar: CHAR 

menu: MenuHandle; item : INTEGER; styleChar : Char 


= 


menuBar : Handle 

menu: MenuHandle; flashCount 
h(2) v(2) 

pnState(4) 

grafPtr(4) 

theBitMap(4) 

pt(4) h(2) v(2) 
Pointer(idAO) Size(idDO) 
VAR r: Rect; left, top, right, bottom: Integer 
rgn: RgnHandle; left, top, right, bottom: Integer; 
theResource: Handle; attrs: INTEGER 

theResource: Handle; theId: INTEGER; name: Str255 
load: BOOLEAN 


= 


: INTEGER 


File: ToolBox Names 


Report: TrapList 


Selection: Value/Trap: 
through Value/Trap: 


Name: 


eeeccerercecerccece 


SetStdProcs 
SetString 


SetTrapAddress 


SetVol 
SetWindowPic 
SetWRefCon 
SetWTitle 
SetZone 
ShieldCursor 
ShowControl 
ShowCursor 
ShowHide 
ShowPen 
ShowWindow 
SizeControl 
SizeWindow 
SpaceExtra 
Status 
StdArc 
StdBits 
StdComment 
StdGetPic 
StdLine 
StdOval 
StdPoly 
StdPut Pic 
StdRect 
StdRgn 
StdRRect 
StdText 
StdTxMeasure 
StillDown 
StopAlert 
StringWidth 
Stuf fHex 
SubPt 
SystemClick 
SystemEdit 
SystemError 
SystemEvent 
SystemMenu 
SystemTask 
TEActivate 
TECalText 
TECLick 
TECopy 
TECut 
TEDeactivate 


Value/ 
ACEA 
ADO7 
A047 
AOQL5 
AD2E 
AD18 
ADLA 
AOQ1B 
AC55 
AD57 
AC53 
ADO8 
AC97 
ADL5 
AD5C 
ADLD 
AC8E 
A005 
ACBD 
ACEB 
ACF 1 
ACEE 
AC90 
ACB6 
ACC5 
ACFO 
ACAO 
ACD1L 
ACAF 
AC82 
ACED 
AD73 
AD86 
AC8C 
AC66 
AC7F 
ADB 3 
ADC2 
ADC9 
ADB2 
ADB5 
ADB4 
ADD8 
ADDO 
ADD4 
ADD5 
ADD6 
ADDI 
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Fields: 


sh : StringHandle; str : Str40 
theWindow: WindowPtr; data: LongInt 
theWindow: WindowPtr; title: Str255 
theZone( idAO) 


©. 


theControL 


= 


: ControlHandle 


theWindow: WindowPtr 

theControl : ControlHandle; w, h : INTEGER 

theWindow: WindowPtr; width,height: Integer; fUpdate: Boolean 
extra(2) 

verb : GrafVerb ; r : Rect ; startAngle, arcAngle : INTEGER 
VAR scrBits : BitMap; VAR srcRect, dstRect : Rect; mode : Inte 


2 


= 


newPt(4) 

verb : GrafVerb ; r : Rect 

verb : GrafVerb ; poly : PolyHandle 
verb : GrafVerb ; r : Rect 

verb : GrafVerb ; rgn : RgnHandle 
verb : GrafVerb ; r : Rect; ovW, ovH : 
count(2) textAddr(4) 


= 


INTEGER 


= 


alertNo 
s(4) 
thingPtr(4) s(2) 

source(4) dest(4) 

theEvent: EventRecord; theWindow: WindowPtr 


= 


Integer 


theEvent: EventRecord 
menuResult: LongiInt 


File: ToolBox 
Report: TrapList 
Selection: Value 
through Value 
Name: 
TEDeLlete 
TEDispose 
TEIdle 
TEInit 
TEKey 
TENew 
TEPaste 
TEScroll 
TESetSelect 
TESet Text 
TestControl 
TEUpdate 
TextBox 
TextFace 
TextFont 
TextMode 
TextSize 
TextWidth 
TickCount 
TrackControl 
TrackGoAway 
UnionRect 
Unionkgn 
UniqueID 
UnLoad Seg 
UnmountVol 
UnPackBits 
UpdateResFile 
UprString 
UseResFile 
ValidRect 
ValidRgn 
Vinstall 
VRemove 
WaitMouseUp 
Write 
WriteParam 


. WriteResource 


XOrRgn 


Names 


/Trap: 
/Trap: 
Value/ 
ADD7 
ADCD 
ADDA 
ADCC 
ADDC 
ADD2 
ADDB 
ADDD 
ADDL 
ADCF 
AD66 
ADD3 
ADCE 
AC88 
AC87 
AC89 
AC8A 
AC86 
AD75 
AD68 
ADLE 
ACAB 
ACES 
ADC1L 
ADF 1 
AOOE 
ACDO 
AD99 
AC54 
AD98 
AD2A 
AD29 
A033 
A034 
AD77 
A003 
A038 
ADBO 
ACE7 


equals A000 
equals AFFF 
Fields: 
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SeCSCSeSSeCeCSSSSCCCECST ST SSCSSCSESSSTSE SE SSS STS ST SS SSSS SS SS SSS SCSESCOCSETSETSe 


theControl : ControlHandle; thePt : Point 


face(2) 
font(2) 
mode(2) 
size(2) 
textBuf(4) firstByte(2) byteCount(2) 


= 


theControl : ControlHandle; actionProc 
srcl, src2: Rect; VAR dst: Rect 
srcRgnA, srcRgnB, dstRgn: RgnHandle 
refnum: INTEGER 

refnum: INTEGER 

goodRect : Rect 

goodRgn : RgnHandle 


srcRgnA, srcRgnB, dstRgn: RgnHandle 


: ProcPtr 


replacing 33, 54 
selecting 47, 48 

text format 68, 69, 70, 71 

title bar 9 

type size 90, 91, 96 
changing 24, 62 
preset 91, 96 
removing 62 

type style 90, 96 
changing 24, 62 
preset 91, 96 
removing 62 

typeface 27, 63 
preset 63 


Underline command 24 

Undo command 19, 89 

Undo Ruler Change command 19 
Undo Typing command 12 

up arrow 18 


windows 82 


word wraparound 10, 11, 12, 32, 8 


wristwatch 8 
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ABOUT THIS MANUAL 
ABOUT THIS MANUAL 


This manual describes the overall structure of a Macintosh application 
program, including its interface with the Finder. *** Right now it 
describes only the Finder-interface; the rest will be filled in later. 
Eventually it will become part of a comprehensive manual describing the 
entire Toolbox and Operating System. *** 


(hand ) 
This information in this manual applies to version 7 of 
the Macintosh ROM and version 1. of the Finder. 


You should already be familiar with the following: 


- The details of the User Interface Toolbox, the Macintosh Operating 
System, and the other routines that your application program may 
call. For a list of all the technical documentation that provides 
these details, see Inside Macintosh: A Road Map. 


~ The Finder, which is described in the Macintosh owner's guide. 


This manual doesn't cover the steps necessary to create an 
application's resources or to compile, link, and execute the 
application program. These are discussed in the manual Putting 


Together & Macintosh Application. 


The manual begins with sections that describe the Finder interface: 
signatures and file types, used for identification purposes; 
application resources that provide icon and file information to the 
Finder; and the mechanism that allows documents to be opened or printed 
from the Finder. 


*** more to come *** 


Finally, there's a glossary of terms used in this manual. 


eee 
SIGNATURES AND FILE TYPES 


Every application must have a unique signature by which the Finder can 
identify it. The signature can be any four-character sequence not 
being used for another application on any currently mounted volume 
(except that it can't be one of the standard resource types). To 
ensure uniqueness on all volumes, your application's signature must be 
assigned by Macintosh Technical Support. 


Signatures work together with file types to enable the user to open or 
print a document (any file created by an application) from the Finder. 
When the application creates a file, it sets the file's creator and 
file type. Normally it sets the creator to its signature and the file 
type to a four-character sequence that identifies files of that type. 
When the user asks the Finder to open or print the file, the Finder 
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starts up the application whose signature is the file's creator and 
passes the file type to the application along with other identifying 
information, such as the file name. (More information about this 
process is given below under "Opening and Printing Documents from the 
Finder". 
An application may create its own special type or types of files. Like 
signatures, file types must be assigned by Macintosh Technical Support 
to ensure uniqueness. When the user chooses Open from an application's 
File menu, the application will display (via the Standard File Package) 
the names of all files of a given type or types, regardless of which 
application created the files. Having a unique file type for your 
application's special files ensures that only the names of those files 
will be displayed for opening. 
(hand) ~ 

Signatures and file types may be strange, unreadable 

combinations of characters; they're never seen by end 

users of Macintosh. 


Applications may also create existing types of files. There might, for 
example, be one that merges two MacWrite documents into a single 
document. In such cases, the application should use the same file type 
as the original application uses for those files. It should also 
specify the original application's signature as the file's creator; 
that way, when the user asks the Finder to open or print the file, the 
Finder will call on the original application to perform the operation. 
To learn the signatures and file types used by existing applications, 
check with Macintosh Technical Support. 


Files that consist only of text-—a stream of characters, with Return 
characters at the ends of paragraphs or short lines--should be given 
the file type ‘'TEXT'. This is the type that MacWrite gives to 
text-only files it creates, for example. If your application uses this 
file type, its files will be accepted by MacWrite and it in turn will 
accept MacWrite text-only files (likewise for any other application 
that deals with 'TEXT' files). Your application can give its own 
signature as the file's creator if it wants to be called to open or 
print the file when the user requests this from the Finder. 


For files that aren't to be opened or printed from the Finder, as may 
be the case for certain data files created by the application, the 
signature should be set to '??7?' (and the file type to whatever is 
appropriate). 


FINDER-RELATED RESOURCES 


To establish the proper interface with the Finder, every application's 
resource file must specify the signature of the application along with 
data that provides version information. In addition, there may be 
resources that provide information about icons and files related to the 
application. All of these Finder-related resources are described 
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FINDER-RELATED RESOURCES 5 


a 


below, followed by a comprehensive example and (for interested 
programmers) the exact formats of the resources. 


Version Data 

Your application's resource file must contain a special resource that 
has the signature of the application as its resource type. This 
resource is called the version data of the application. The version 
data is typically a string that gives the name, version number, and 
date of the application, but it can in fact be any data at all. The 
resource ID of the version data is § by convention. 


As described in detail in Putting Together a Macintosh Application, 
part of the process of installing an application on the Macintosh is to 
set the creator of the file that contains the application. You set the 
creator to the application's signature, and the Finder copies the 
corresponding version data into a resource file named Desktop. (The 
Finder doesn't display this file on the Macintosh desktop, to ensure 
that the user won't tamper with it.) 


(hand ) 
Additional, related resources may be copied into the 
Desktop file; see "Bundles" below for more information. 
The Desktop file also contains folder resources, one for 
each folder on the volume. 


Icons and File References 
For each application, the Finder needs to know: 
~ The icon to be displayed for the application on the desktop, if 
different from the Finder's default icon for applications (see 
Figure 1). 
- If the application creates any files, the icon to be displayed for 
each type of file it creates, if different from the Finder's 


default icon for documents. 


~ What files, if any, must accompany the application when it's 
transferred to another volume. 


@ 10 


Application Document 
Figure 1. The Finder's Default Icons 
The Finder learns this information from resources called file 


references in the application's resource file. Each file reference 
contains a file type and an ID number, called a local ID, that 
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identifies the icon to be displayed for that type of file. (The local 
ID is mapped to an actual resource ID as described under "Bundles" 
below.) Any file reference may also include the name of a file that 
must accompany the application when it's transferred to another volume. 


The file type for the application itself is 'APPL'. This is the file 
type in the file reference that designates the application's icone You 
also specify it as the application's file type at the same time that 
you specify its creator—the first time you install the application on 
the Macintosh. 


The ID number in a file reference corresponds not to a single icon but 
to an icon list in the application's resource file. The icon list 
consists of two icons: the actual icon to be displayed on the desktop, 
and a mask consisting of that icon's outline filled with black (see 
Figure 2). *** For existing types of files, there's currently no way 
to direct the Finder to use the original application's icon for that 


file type. %*** 
Icon Mesk 


Figure 2. Icon and Mask 


Bundles 


A bundle in the application's resource file groups together all the 
Finder-related resources. It specifies the following: 


- The application's signature and the resource ID of its version 
data 


- A mapping between the local IDs for icon lists (as specified in 
file references) and the actual resource IDs of the icon lists in 
the resource file 


- Local IDs for the file references themselves and a mapping to 
their actual resource IDs 


The first time you install the application on the Macintosh, you set 
its "bundle bit", and the Finder copies the version data, bundle, icon 
lists, and file references from the application's resource file into 
the Desktop file. *** (The setting of the bundle bit will be covered 
in the next version of Putting Together a Macintosh Application.) 

“ex If there are any resource ID conflicts between the icon lists and 
file references in the application's resource file and those in 
Desktop, the Finder will change those resource IDs in Desktope The 
Finder does this same resource copying and ID conflict resolution when 
you transfer an application to another volume. 


H fa/s//oL Deek ye ee ee Fe a ee pen ee ee Be 


oe, 
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(hand ) 
The local IDs are needed only for use by the Finder. 


An Example 


Suppose you've written an application named SampWriter. The user can 
create a unique type of document from it, and you want a distinctive 
icon for both the application and its documents. The application's 
signature, as assigned by Macintosh Technical Support, is "SAMP'; the 
file type assigned for its documents is 'SAMF’. Furthermore, a file 
named 'TgFil' should accompany the application when it's transferred to 
another volume. You would include the following resources in the 
application's resource file: 


Resource Resource ID Contents 
Version data with 6 The string 'SampWriter Version 1 
resource type 'SAMP' — 2/1/84" 
Icon list 128 The icon for the application 
The icon's mask 
Icon list 129 The icon for documents 
The icon's mask 
File reference 128 File type ‘APPL' 
Local ID § for the icon list 
File reference 129 File type ‘SAMF' 


Local ID 1 for the icon list 
File name 'TgFil' 
Bundle 128 Signature 'SAMP' 
Resource ID @ for the version data 
For icon lists, the mapping: 


local ID ¢ —> resource ID 128 
local ID 1.—)> resource ID 129 


For file references, the mapping: 


local ID § —> resource ID 128 
local ID 1 —> resource ID 129 


(hand ) 
See the manual Putting Together & Macintosh Application 
for information about how to include these resources in a 
resource file. 


The file references in this example happen to have the same local IDs 
and resource IDs as the icon lists, but any of these numbers can be 
different. Different resource IDs can be given to the file references, 
and the local IDs specified in the mapping for file references can be 
whatever desired. 
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Formats of Finder-Related Resources 


The resource type for an application's version data is the signature of 
the application, and the resource ID is § by convention. The resource 
data can be anything at all; typically it's a string giving the name, 
version number, and date of the application. 


The resource type for an icon list is ‘ICN#'. The resource data simply 
consists of the icons, 128 bytes each. 


The resource type for a file reference is 'FREF'. The resource data 
has the format shown below. 


Number of -bytes Contents 


4 bytes File type 

2 bytes Local ID for icon list 

1 byte Length of following file name in bytes; 
$ if none | 

n bytes Optional file name 


The resource type for a bundle is 'BNDL'. The resource data has the 
format shown below. The format is more general than needed for 
Finder-related purposes because bundles will be used in other ways in 
the future. 


Number of bytes Contents 


4 bytes Signature of the application 
2 bytes Resource ID of version data 
2 bytes Number of resource types in bundle minus 1 
For each resource type: 
4 bytes Resource type 
2 bytes Number of resources of this type minus l 
For each resource: 
2 bytes Local ID 
2 bytes Actual resource ID 


A bundle used for establishing the Finder interface contains the two 
resource types ‘ICN#' and 'FREF'. 


OPENING AND PRINTING DOCUMENTS FROM THE FINDER 


When the user selects a document and tries to open or print it from the 
Finder, the Finder starts up the application whose signature is the 
document file's creator. An application may be selected along with one 
or more documents for opening (but not printing); in this case, the 
Finder starts up that application. If the user selects more than one 
document for opening without selecting an application, the files mst 
have the same creator. If more than one document is selected for 
printing, the Finder starts up the application whose signature is the 
first file's creator (that is, the first one selected if they were 
selected by Shift-clicking, or the top left one if they were selected 
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by dragging a rectangle around them). 


Any time the Finder starts up an application, it passes along 
information via the "Finder information handle" in the application 
parameter area (as described in the Segment Loader manual). Pascal 
programmers can call the Segment Loader procedure GetAppParms to get 
the Finder information handle. For example, if applParam is declared 
as type Handle, the call 


GetAppParms(applName, applRefNum, applParam) 


returns the Finder information handle in applParam. The Finder 
information has the following format: 


Number of bytes Contents 


2 bytes @ if open, 1 if print 
2 bytes Number of files to open or print (@ if none) 
For each file: 

2 bytes Volume reference number of volume containing 

the file | 

4 bytes File type 

l byte File's version number (typically @ 

1 byte Ignored 

l byte Length of following file name in bytes 

n bytes Characters of file name (if n is even, add 


an extra byte) 


The files are listed in order of the appearance of their icons on the 
desktop, from left to right and top to bottom. The file names don't 
include a volume prefix. An extra byte is added to any name of even 
length so that the entry for the next name will begin on a word 
boundary. 


Every application that opens or prints documents should look at this 
information to determine what to do when the Finder starts it upe If 
the number of files is §, the application should start up with an 
untitled document on the desktop. If a file or files are specified for 
opening, it should start up with those documents on the desktop. If 
only one document can be open at a time but more than one file is 
specified, the application should open the first one and ignore the 
rest. If the application doesn't recognize a file's type (which can 
happen if the user selected the application along with another 
application's document), it may want to open the file anyway and check 
its internal structure to see if it's a compatible type. The response 
to an unacceptable type of file should be an alert box that shows the 
file name and says that the document can't be opened. 


If a file or files are specified for printing, the application should 
print them in turn, preferably without doing its entire start-up 
Sequence. For example, it may not be necessary to show the menu bar or 
a document window, and reading the desk scrap into memory is definitely 
not required. After successfully printing a document, the application 
should set the file type in the Finder information to §. Upon return 
from the application, the Finder will start up other applications as 
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necessary to print any remaining files whose type was not set to @. 
***k The Finder doesn't currently do this, but it may in the future. 
kik 
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ea ee Nee ee 
bundle: A resource that maps local IDs of resources to their actual 
resource IDs; used to provide mappings for file references and icon 
lists needed by the Finder. 


Desktop file: A resource file in which the Finder stores folder 
resources and the version data, bundle, icons, and file references for 
each application on the volume. 


file reference: A resource that provides the Finder with file and icon 
information about an application. 


file type: A four-character sequence, specified when a file is 
created, the identifies the type of file. 


icon list: A resource consisting of a list of icons. 


local ID: A number that refers to an icon list or file reference in an 
application's resource file and is mapped to an actual resource ID by a 
bundle. 


signature: A four-character sequence that uniquely identifies an 
application to the Finder. 


version data: In an application's resource file, a resource that has 
the application's signature as its resource type; typically a string 
that gives the name, version number, and date of the application. 
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“COMMENTS? 


Macintosh User Education encourages your comments on this manual. 
~ What do you like or dislike about it? 

~ Were you able to find the information you needed? 

- Was it complete and accurate? 

~ Do you have any suggestions for improvement? 


Please send your comments to the author (indicated on the cover 
page) at 10460 Bandiey Drive M/S 3-G, Cupertino CA 95014. 
Mark up a copy of the manual or note your remarks separately. 


(We'll return your marked-up copy # you like.) 


Thanks for your help! 


MACPAINT 
FORMAT 


The MacPaint Document Format 
by Bill Atkinson 


MacPaint documents are easy to read and write, and have become a 
Standard interchange format for full-page bitmap images on Macintosh. 
Their Internal format is described here to aid program developers in 
generating and reading MacPaint documents. 


MacPaint documents use only the data fork of the file system; the resource 
fork is not used and may be ignored. The data fork contains a 512 byte 
header and then the compressed data representing a single bitmap of 576 
pixels wide by 720 pixels tall. At 72 pixels per inch, this bitmap occupies 
the full 8 by 10 inch printable area of the Imagewriter printer page. 


HEADER: 


The first S12 bytes of the document form a header with a 4 byte version 
number (default = 2), then 38*8 = 304 bytes of patterns, then 204 unused 
bytes reserved for future expansion. If the version number is zero, the 
rest of the header block is ignored and default patterns are used, so 
programs generating MacPaint documents can simply write out 512 bytes 
of zero as the document header. Most programs which read MacPaint 
documents can simply skip over the header when reading. 


BITMAP: 


Following the header are 720 compressed scanlines of data which form the 
576 wide by 720 tall bitmap. Without compression, this bitmap would 
occupy 51840 bytes and chew up disk space pretty fast; typical MacPaint 
documents compress to about 10 Kbytes using the PackBits procedure in 
the Macintosh ROM to compress runs of equal bytes within each scanline. 
The bitmap part of a MacPaint document is simply 720 times the output of 
PackBits with 72 bytes input. 
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READING SAMPLE: 


CONST srcBlocks = 2; {at least 2, bigger makes it faster } 
srcSize = 1024; (512 * srcBlocks ) 

TYPE diskBlock = PACKED ARRAY[1..512] OF QDByte; 

VAR srcBuf: ARRAY[1..srcBlocks] OF diskBlock; 
srcPtr,dstPtr. QDPtr; 


( skip the header ) 
ReadData(srcFile,@srcBuf,512); 


{ prime srcBuf } 
ReadData(srcF ile,@srcBuf,srcSize); 


( unpack each scanline into dstBits, reading more source as needed } 
srcPtr := @srcBuf; 
dstPtr := dstBits.baseAddr; 
FOR scanLine := 1 to 720 DO 
BEGIN 
UnPackBits(srcPtr,dstPtr, 72); ( bumps both ptrs } 
( time to read next chunk of packed source 7 ) 
IF ORD(srcPtr) > ORD(@srcBuf) + srcSize - S12 THEN 
BEGIN 
srcBuf[1) := srcBuf[srcBlocks); ( move up last block } 
ReadData(srcFile,@srcBuf[2],srcSize-5 | 2); 
srcPtr := Pointer{ORD(srcPtr) - srcSize + 512); 
END; 
END; 


WRITING SAMPLE: ; 
To write out a 576 by 720 bitmap which is contained in memory, the 
following fragment of code could be used: 


TYPE diskBlock = PACKED ARRAY[1..512] OF QDByte; 
VAR srcPtr,dstPtr. QDPtr; 

dstBuf: diskBlock; 

dstBytes: INTEGER; 


( write the header, all zeros ) 
FOR ij := 1 to 512 DO dstBuf[i] := 0; 
WriteData(dstFile,@dstBuf,5 12); 


( Compress each scanline and write it ) 
srcPtr := srcBits.baseAddr; 
FOR scanLine := 1 to 720 DO 
BEGIN 
dstPtr := @dstBuf; 
PackBits(srcPtr,dstPtr, 72); ( bumps both ptrs } 
dstBytes := ORD(dstPtr) - ORD(@dstBuf); (calc packed size } 
WriteData(dstF ile, @dstBuf,dstBytes); ( write packed data } 
END; 


PASCAL SER. 
DRIVER 


To: . Macintosh Software Developers 
From: Martin P. Haeberli 
Date: February 19, 1984 


Subject: How to use the Pascal Support Package for the Macintosh 
Serial Driver. 


This note is for experts only. I am assuming that you have read and 
understood the ‘ ‘Async Driver” section of the Inside Macintosh 
documentation. We are providing this package to you as a gift, 
Without support. This means no questions, please! I know you will 
ask them anyway, but please please please go easy on us. This 
package is absolutely not formally released, supported, or 
documented. If you have decided to proceed anyway, I encourage you 
toread af /east all of the xxxDefs Pascal source code, and skim the 
xxxI mpl Pascal source code, so that you have a general understanding 
of how to use this stuff. 


The Macintosh ROM contains a Serial Driver for both Macintosh Serial 
Ports. This driver supports asynchronous serial I/O only, at speeds 
from about 150 baud up to speeds over 19.2 K baud. There are also a 
few known bugs in the ROM-based version of the driver, especially 
where support for XON-XOFF flow control is concerned. 


In developing the Macintosh Terminal Emulator program, 

MacTer minal, I chose to build a set of Pascal interfaces for the serial 
driver on top of the Macintosh IO system interfaces published in 
OSIntf.text. This package, which is implemented mostly in Pascal with 
a little bit of assembly language, provides the programmer with a 
RAM-based version of the Async Serial Driver which solves all known 
bugs, as well as providing support for speeds down to as slow as 50 
baud, and providing the opportunity for user extensions to the Async 
Serial Driver where necessary. 


The package comes in a number of parts, here listed in compilation 
order: 


Async.text: Assembly Language source tert for the RAM-based 
Async Serial Driver. Depends on: SysEqu.text 
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Execute.text: Assembly Language support for SerImpl! and others. 
Depends on: SysEqu.text 
Systlacs.text 


TaskAsm.text: Assembly Language support for TaskImpl. Depends on: 
SysEqu. text 
Systlacs. text 


TaskDefs.text: Defines interface to TaskImpl. Depends on: 
; OSintf 


TaskI mpl.text:Pascal Support for simple multitasking system used by 
Pascal interface to serial driver. Depends on: 
QuickDraw 
OSintf 
TaskDefs 


PipeDefs.text: Defines interface to PipeImpl. Depends on: 
QuickDrae 
OSIntf 
Tool Int f 


Pipel mpl.text: Pascal support for a simple fifo buffer/stream interface 
used by Pascal Interface to serial driver. Depends on: 
QuickDras 
OSInt f 
Toolintf 
PipeDefs 


SerDefs.text: Defines interface to Serlmpl. Depends on: 
QuickDrae 
OSintf 
Tool Intf 
PipeDefs 
TaskDefs 
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Serlmpl.text The actual Pascal support for Asynchronous Serial 
; Driver. Knows how to load and install the RAM-based 
driver, how to unload it, how to set serial line 
parameters individually, how to take stuff from a pipe 
and send it to the serial port, and how to take stuff 
from the serial port and save it in a pipe. Depends on: 
QuickDras 
OSintf 
Tool Int f 
PipeDefs 
TaskDefs 


To link this in to your program, include the following stub in your 
linker com mand file: 

obj :0STraps 

obj : Tool Traps 

Execute 

TaskAse 

Task lap! 

Pipelap! 

Serlapl 

obj :MacPasLib 


Also, you must include the following stub in your rmaker command 
file in order to include the RAM-based Async driver in your resource 
file: 
Type SERD = WDEF 
ASync,, 256 
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Now, for an example of how to use this stuff with your program. 


SerDemo ; . 
Uses ($U obj:QuickDraw } QuickDrow, 
{$U obj :OSintf } OSintf, 
{$U obj : Tool Intf } Tool intf, 
{$U PipeDefs } PipeDefs, 
{$U TaskDefs } TaskDefs, 
{$U SerDefs } SerDefs; 
Const 
SinPipeSize = 512; 
SOutPipeSize = 236; 
Ver a 
done : Boo | ean; 
pipeSin: Pipe; { Serial input pipe: characters arrive here } 
pipeSOut: Pipe; { Serial output pipe: send characters here } 
serPort: Ser; { Serial Object pointer } 
ch: Char ; { temporary character } 
theEvent: EventRecord; { used by GetNextEvent below } 
Procedure Ini tSerDemo; 
Begin 
Ini tTasks; { Initialize aul ti tasking package } 
{ open an input pipe for SimPipeSize characters } 
pipeSin := PipeOpen(SinPipeSize); 
{ open an output pipe for SOutPipeSize characters } 
PipeSOut := PipeOpen(SOut? ipeSi ze); 
Ini tSer; { Initializes the serial package } 
serPort := NewSer; { Allocates a serial object } 
{ Open serPort onto Serial Port A (telephone port) } 
OpenSer(serPort, SPortfA, pipeSin, pipeSOut);. 
{ choices for settings stuff are listed in Serfefs } 
SetSerSpeed(serPort, SSp9600); { set speed to 9600 } 
SetSerPar i ty(serPort, SParOdd); { set parity to Odd } 
{ set character sidth to 8 bits/character } 
SetSerHidth(serPort, SUid8); 
SerSerStop(serPort, SStp1); { set no. of stop bits to 1 bit } 
End; 
Procedure EndSerDemo; 
Begin 
CloseSer<serPort); { close the serial port } 
serPort := Mil; 
PipeClose(pipeSin); { close the input pipe } 
PipeClose(pipeSOut>; { close the output pipe } 
EndSer ; { Shut down the serial package } 
EndTasks ; { Shut down multitasking } 


End; 
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Ini tSerDemo ; 
done := False; 
While Not Done Do 


Begin 


Sys temTask ; 


‘RunTasks ; { This runs the simple multitasking systea } 


While Pipefvail<(pipeSin> > 0 Do 
Begin 
ch := PipeGet(pipeSin); { ch is next char } 
{ process char here or elseshere } 


End; 
While PipeLeft<pipeSOut) > 0 Do 
Begin 
{ generate next char } 
PipePut<pipeSOut, ch); { ch is char to send } 
End; 
If GettextEvent(everyEvent, theEvent> Then 
Begin 
{ handle events as you like here. } 


, 


ted FO 2 fe; 


